Astro-turnstile NPM

`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:

Install the required dependencies

pnpm add astro-turnstile

npm install astro-turnstile

yarn add astro-turnstile

bun add astro-turnstile

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';