Astro Turnstile

This is an Astro integration that allows you to add a turnstile to your Astro site.

Usage

Prerequisites

Before you can use this integration, you need to have a Cloudflare account. You can sign up for a free account here.

Getting Started

First, you need to create a new site in your Cloudflare account. You can do this by following the instructions here.

Once you have created a site, you will be given a site key and a secret key. You will need this key to configure the integration.

Installation

Install the integration automatically using the Astro CLI:

pnpm astro add astro-turnstile

npx astro add astro-turnstile

yarn astro add astro-turnstile

bunx astro add astro-turnstile

Or install it manually:

1. Install the required dependencies

pnpm add astro-turnstile

npm install astro-turnstile

yarn add astro-turnstile

bun add astro-turnstile

2. Add the integration to your astro config

+import astroTurnstile from "astro-turnstile";

export default defineConfig({
  integrations: [
+    astroTurnstile(),
  ],
});

Configuration

.env File

You will need to add these 2 values to your .env file:

• TURNSTILE_SITE_KEY (required): Your Turnstile site key
• TURNSTILE_SECRET_KEY (required): Your Turnstile secret key - this should be kept secret

Astro Config Options

verbose

• Type: boolean
• Default: false

Enable verbose logging.

disableClientScript

• Type: boolean
• Default: false

Disable the client-side script injection.

By default, the client-side script is injected into the Astro project on every page. In some cases, you may want to disable this behavior, and manually inject the script where needed. This option allows you to disable the client-side script injection.

Note: If you disable the client-side script injection, you will need to manually inject the Turnstile client-side script into your Astro project.

disableDevToolbar

• Type: boolean
• Default: false

Disable the Astro Turnstile Dev Toolbar App.

endpointPath

• Type: string
• Default: /verify

The path to the injected Turnstile API endpoint.

Usage

The following components are made available to the end user:

• TurnstileWidget - The main widget component for displaying the Turnstile captcha field in forms

  • Available Props:
    • theme:
      • Type: "auto" | "light" | "dark" | undefined
      • Default: "auto"
    • size:
      • Type: "normal" | "compact" | "flexible" | undefined
      • Default: "normal"
    • margin:
      • Type: string | undefined
      • Default: "0.5rem"

• TurnstileForm - A helper form element that assists you in building your forms with Turnstile verification built in

  • Available Props:
    • (All the props from Widget)
    • enctype
      • Type: "multipart/form-data" | "application/x-www-form-urlencoded" | "submit" | undefined
      • Default: "application/x-www-form-urlencoded"
    • action
      • Type: string | null | undefined
    • method
      • Type: string | null | undefined

These components can be accessed by either of the following methods:

// Option 1: Runtime virtual module
import TurnstileWidget from 'astro-turnstile:components/TurnstileWidget';
import TurnstileForm from 'astro-turnstile:components/TurnstileForm';

// Option 2: Direct package exports
import TurnstileWidget from 'astro-turnstile/components/TurnstileWidget';
import TurnstileForm from 'astro-turnstile/components/TurnstileForm';

Contributing

This package is structured as a monorepo:

• playground contains code for testing the package
• package contains the actual package

Install dependencies using pnpm:

pnpm i --frozen-lockfile

Start the playground:

pnpm playground:dev

You can now edit files in package. Please note that making changes to those files may require restarting the playground dev server.

Licensing

MIT Licensed. Made with ❤️ by Hunter Bertoson.

Acknowledgements

Astro Turnstile Florian Lefebvre