📝 hCaptcha Forms in SvelteKit

In this post we look at a SvelteKit hCaptcha contact form for your Svelte site. hCaptcha is an alternative to Google reCAPTCHA. Both can be used to reduce spam submissions on your site's forms. hCaptcha claims to protect user privacy. By asking users to complete the hCaptcha challenge before submitting your form, you can filter some responses and further scrutinise them, based on the hCaptcha verdict.

There are two parts to the hCaptcha verification. The first is on the client side (frontend), where we ask the user to complete the challenge. We send the user challenge responses to hCaptcha straight away (from the client). hCaptcha then responds with a response code. That response code is needed in the second part of the process, which is completed in the backend. We will see how you can use Cloudflare workers to perform the backend part if you want to build a static SvelteKit site. If, however, you prefer server side rendered, we cover you back with some sample code for handling that in SvelteKit too.

If that all sounds exciting, why don't we crack on?

🧱 hCaptcha Forms in SvelteKit

The plan of action is the following:

1. Clone the SvelteKit blog MDsveX starter, so we can hit the ground running.

2. Add a contact form.

3. Add the hCaptcha client code.

4. Look at how Cloudflare workers can be used for the server side verification.

5. Try an alternative server side rendered implementation.

⚙️ Getting Started

Let's get started by cloning the SvelteKit blog MDsveX starter:

git clone https://github.com/rodneylab/sveltekit-blog-mdx.git sveltekit-hcaptcha-form
cd sveltekit-hcaptcha-form
pnpm install
cp .env.EXAMPLE .env
pnpm run dev

We will also use some components from a SvelteKit component library to speed up development. Let's install those now too:

pnpm install -D @rodneylab/sveltekit-components

Finally, you will need hCaptcha credentials to test out your code. See instructions on setting up a free hCaptcha account in the article on Serverless hCaptcha or just head to the hCaptcha site. Once you have credentials add them to your .env file:

VITE_HCAPTCHA_SITEKEY="10000000-ffff-ffff-ffff-000000000001"
VITE_WORKER_URL="http://127.0.0.1:8787"

HCAPTCHA_SECRETKEY="0x0000000000000000000000000000000000000000"

The first two credentials will be accessed by the client side so they need the VITE_ prefix.

As a last piece of setup, import the dotenv package in your svelte.config.js file:

/** @type {import('@sveltejs/kit').Config} */
import 'dotenv/config';
import adapter from '@sveltejs/adapter-static';

Then we allow access to client components in src/lib/config/website.js:

  wireUsername: import.meta.env ? import.meta.env.VITE_WIRE_USERNAME : '',
  hcaptchaSitekey: import.meta.env ? import.meta.env.VITE_HCAPTCHA_SITEKEY : '',
  workerUrl: import.meta.env ? import.meta.env.VITE_WORKER_URL : '',
};

With the setup out of the way, if this is your first time using the starter, have a skim through the files and folders of the project. Also head to localhost:3030/ and do some clicking around, to familiarise yourself with the site. When you're ready to carry on.

⚓️ Hooks Configuration

We just need to tweak the hooks configuration for everything to run smoothly. The src/hooks.js file in the project includes Content Security Policy (CSP) headers. These are an added security measure which only allow the browser to connect to certain hosts. For any site you build with the starter, you will probably need to tweak this file. We need to allow connections to hCaptcha and our Cloudflare worker for this project:

const directives = {
  'base-uri': ["'self'"],
  'child-src': ["'self'"],
  // 'connect-src': ["'self'", 'ws://localhost:*'],
  'connect-src': [
    "'self'",
    'ws://localhost:*',
    'https://hcaptcha.com',
    'https://*.hcaptcha.com',
    process.env['VITE_WORKER_URL'],
  ],
  'img-src': ["'self'", 'data:'],
  'font-src': ["'self'", 'data:'],
  'form-action': ["'self'"],
  'frame-ancestors': ["'self'"],
  'frame-src': [
    "'self'",
    // "https://*.stripe.com",
    // "https://*.facebook.com",
    // "https://*.facebook.net",
    'https://hcaptcha.com',
    'https://*.hcaptcha.com',
  ],
  'manifest-src': ["'self'"],
  'media-src': ["'self'", 'data:'],
  'object-src': ["'none'"],
  // 'style-src': ["'self'", "'unsafe-inline'"],
  'style-src': ["'self'", "'unsafe-inline'", 'https://hcaptcha.com', 'https://*.hcaptcha.com'],
  'default-src': [
    "'self'",
    rootDomain,
    `ws://${rootDomain}`,
    // 'https://*.google.com',
    // 'https://*.googleapis.com',
    // 'https://*.firebase.com',
    // 'https://*.gstatic.com',
    // 'https://*.cloudfunctions.net',
    // 'https://*.algolia.net',
    // 'https://*.facebook.com',
    // 'https://*.facebook.net',
    // 'https://*.stripe.com',
    // 'https://*.sentry.io',
  ],
  'script-src': [
    "'self'",
    "'unsafe-inline'",
    // 'https://*.stripe.com',
    // 'https://*.facebook.com',
    // 'https://*.facebook.net',
    'https://hcaptcha.com',
    'https://*.hcaptcha.com',
    // 'https://*.sentry.io',
    // 'https://polyfill.io',
  ],
  'worker-src': ["'self'"],
  // remove report-to & report-uri if you do not want to use Sentry reporting
  'report-to': ["'csp-endpoint'"],
  'report-uri': [
    `https://sentry.io/api/${import.meta.env.VITE_SENTRY_PROJECT_ID}/security/?sentry_key=${
      import.meta.env.VITE_SENTRY_KEY
    }`,
  ],
};

You will need to make these changes during development, whether you are creating a static or server side rendered site. For a static production site, the file is not used. You can add HTTP headers to achieve the same effect. Check how to do this with your hosting platform.

🧑🏽 Contact Form

Here's the code for the basic contact form. We are using the component library to save us typing out all the boiler plate needed for accessible form inputs. You can see how to create you own SvelteKit component library in a recent video post. Paste the code into a new file at src/lib/components/ContactForm.svelte:

<script>
  import { EmailInputField, TextArea, TextInputField } from '@rodneylab/sveltekit-components';
  import website from '$lib/config/website';
  import { onMount, onDestroy } from 'svelte';
  import { browser } from '$app/env';

  const { hcaptchaSitekey, workerUrl } = website;

  onMount(() => {

  });

  onDestroy(() => {

  });

  let name = '';
  let email = '';
  let message = '';
  let errors: {
    name?: string;
    email?: string;
    message?: string;
  };
  $: errors = {};
  $: submitting = false;

  function clearFormFields() {
    name = '';
    email = '';
    message = '';
  }

<form class="form" on:submit|preventDefault={handleSubmit}>
  <h2>Drop me a message</h2>
  <TextInputField
    id="form-name"
    value={name}
    placeholder="Your name"
    title="Name"
    error={errors?.name ?? null}
    on:update={(event) => {
      name = event.detail;
    }}
    style="padding-bottom:1rem"
  />
  <EmailInputField
    id="form-email"
    value={email}
    placeholder="blake@example.com"
    title="Email"
    error={errors?.email ?? null}
    on:update={(event) => {
      email = event.detail;
    }}
    style="width:100%;padding-bottom:1rem"
  />
  <TextArea
    id="form-message"
    value={message}
    placeholder="Enter your message here"
    title="Message"
    error={errors?.message ?? null}
    on:update={(event) => {
      message = event.detail;
    }}
    style="padding-bottom:1rem"
  />
  <button type="submit" disabled={submitting}>Submit form</button>
</form>

<style lang="scss">
  .form {
    display: flex;
    flex-direction: column;
    width: 80%;
    margin: $spacing-6 auto;
  }
  button {
    cursor: pointer;
    padding: $spacing-2 $spacing-0;
  }
</style>

The EmailInputField, TextArea and TextInputField components come from the component library. They make use of Svelte's component events to keep the value displayed in sync with the email, message and name variables in this component. Follow the previous link to the Svelte tutorial if you are not yet familiar with this API.

To stop this post getting too long, we won't go into detail on the rest of the form code here. That said, do let me know if you would appreciate a separate post on Svelte forms and binding form fields to variables.

🤖 Adding hCaptcha

We will add the client hCaptcha script directly to the DOM. You have probably seen this pattern if you have looked at tracking or analytics code previously. In SvelteKit, you will see you don't need to add any extra packages to make this work. Before we do that, let's actually load the script in the component onMount function:

  let hcaptcha = { execute: async (_a, _b) => ({ response: '' }), render: (_a, _b) => {} };
  let hcaptchaWidgetID;

  onMount(() => {
    if (browser) {
      hcaptcha = window.hcaptcha;
      if (hcaptcha.render) {
        hcaptchaWidgetID = hcaptcha.render('hcaptcha', {
          sitekey: hcaptchaSitekey,
          size: 'invisible',
          theme: 'dark',
        });
      }
    }
  });

  onDestroy(() => {
    if (browser) {
      hcaptcha = { execute: async () => ({ response: '' }), render: () => {} };
    }
  });

We are adding an “invisible” hCaptcha, so we will use the hcaptchaWidgetID variable to identify it. The first lines are just there to keep types consistent and to be able to link and unlink the hCaptcha script to a local variable during component creation and destruction. We add our hCaptcha site key in the hCaptcha initialisation, within onMount.

Next we need a handleSubmit function:

  async function handleSubmit() {
    try {
      const { response: hCaptchaResponse } = await hcaptcha.execute(hcaptchaWidgetID, {
        async: true,
      });
      /* for a static site, you can use a Cloudflare worker to manage the server part of the
       * hCaptcha and send your site admin an email with the contact details
       *
       * in this case, use:
       *
       * fetch(`${workerUrl}/verify`, {
       *
       * for a server side rendered app, use the verify endpoint to do the processing:
       *
       * fetch('/verify.json', {
       */
      fetch(`${workerUrl}/verify`, {
        method: 'POST',
        credentials: 'omit',
        headers: {
          'Content-Type': 'application/json',
        },
        body: JSON.stringify({
          name,
          email,
          message,
          response: hCaptchaResponse,
        }),
      });
      console.log('Details: ', { name, email, message });
      clearFormFields();
    } catch (error) {
      console.error('Error in contact form submission');
    }
  }
</script>

The function starts with a hcaptcha.execute function call. This displays the captcha and waits for the user to complete it. It then contacts hCaptcha to get a response which we will need for the second part. Interestingly, execute gathers information on mouse movement while solving the challenge as well as the user answers.

The rest of the function includes two possibilities. If we have a static site, we can send our form data and the hCaptcha response to a Cloudflare worker for processing. If you are a SvelteKit purist and go for a server side rendered site, you can send the request to a SvelteKit endpoint. Let's look at both ways in more detail in a moment.

As we mentioned earlier, we can add the hCaptcha script to the DOM:

<svelte:head>
  <script src="https://js.hcaptcha.com/1/api.js?render=explicit" async defer></script>
</svelte:head>

Then we need a placeholder div for it to render:

  <button type="submit" disabled={submitting}>Submit form</button>
  <div
    id="hcaptcha"
    class="h-captcha"
    data-sitekey={hcaptchaSitekey}
    data-size="invisible"
    data-theme="dark"
  />
</form>

🔗 SvelteKit hCaptcha Contact Form: Linking it all Up

Importantly, we should import the ContactForm component on the contact page, so we can render it:

  import ContactForm from '$lib/components/ContactForm.svelte';

  </div></Card
>
<ContactForm />

<style lang="scss"

🤖 Adding hCaptcha: Rust Cloudflare Worker Style

Cloudflare workers run in a Web Assembly (WASM) environment, which means you can write your code in Rust or even C++ instead of JavaScript if you choose. I like this as a solution because if you are building client sites in SvelteKit as well as other frameworks, you only need to maintain one codebase for parts of your backend. You can use the same code for contact form submission from your SvelteKit and Next apps. Rust also offers opportunities for code optimisation. You can see how to set up a Rust Cloudflare service worker to handle hCaptcha in a recent post. For local testing, you will probably have your worker running on http://127.0.0.1:8787, which is the value we defined in the .env file. You will just need to set it up to listen for POST requests on the /verify route.

🔥 Adding hCaptcha: SvelteKit Server Side Route Style

Finally let's check the SvelteKit way to handle the hCaptcha server side work. Create a new file at src/routes/verify.json.js and paste in the following code:

export async function post(request) {
  try {
    const { name, email, message, response: hCaptchaClientResponse } = request.body;

    const secret = process.env['HCAPTCHA_SECRETKEY'];
    const sitekey = process.env['VITE_HCAPTCHA_SITEKEY'];
    const body = new URLSearchParams({ response: hCaptchaClientResponse, secret, sitekey });

    const response = await fetch('https://hcaptcha.com/siteverify', {
      method: 'POST',
      credentials: 'omit',
      headers: {
        'Content-Type': 'application/x-www-form-urlencoded',
      },
      body: body.toString(),
    });

    const data = await response.json();
    const { success } = data;
    console.log('data: ', data);
    if (success) {
      console.log('hCaptcha says yes!');
    } else {
      console.log('hCaptcha says no!');
    }

    // process name, email and message here e.g. email site admin with message details
    console.log({ name, email, message });

    return {
      status: 200,
    };
  } catch (err) {
    const error = `Error in /verify.json.js: ${err}\
`;
    console.error(error);
    return {
      status: 500,
      error,
    };
  }
}

The hCaptcha request needs to be submitted as form data and the response is JSON. A successful field on the response indicates whether hCaptcha considers the user a bot or not. For more details pull up the hCaptcha docs.

⛔️ SvelteKit hCaptcha Contact For: CORS errors

If you get CORS errors testing the site, you should try tweaking your DNS settings. This involves creating a hostname proxy for 127.0.0.1 (localhost). On MacOS you can add the following line to the /private/etc/hosts file:

  127.0.0.1 test.localhost.com

Then, instead of accessing the site via http://localhost:3030, in your browser use http://test.localhost.com:3030. This worked for me on macOS. The same will work on typical Linux and Unix systems, though the file you change will be /etc/hosts. If you are using DNSCryprt Proxy or Unbound, you can make a similar change in the relevant config files. If you use windows and know how to do this, please drop a comment below to help out other windows users.

🙌🏽 SvelteKit hCaptcha Contact Form: What we Learned

We have just covered the basics here. In a real-world app, you should add verification, at least on the server side. Feedback on the client side is a good idea too to improve user experience.

In this post we learned:

• how to use hCaptcha with SvelteKit,

• a way to integrate Rust Cloudflare workers into a static site, making it easier to share code across different frameworks,

• tweaking the Content Security Policy via the hooks.js file to allow connection to external hosts.

I do hope there is at least one thing in this article which you can use in your work or a side project. As always get in touch with feedback if I have missed a trick somewhere!

You can see the full code for this SvelteKit hCaptcha Contact Form project on the Rodney Lab Git Hub repo.

🙏🏽 SvelteKit hCaptcha Contact Form: Feedback

Have you found the post useful? Do you have your own methods for solving this problem? Let me know your solution. Would you like to see posts on another topic instead? Get in touch with ideas for new posts. Also if you like my writing style, get in touch if I can write some posts for your company site on a consultancy basis. Read on to find ways to get in touch, further below. If you want to support posts similar to this one and can spare a few dollars, euros or pounds, please consider supporting me through Buy me a Coffee.

Finally, feel free to share the post on your social media accounts for all your followers who will find it useful. As well as leaving a comment below, you can get in touch via @askRodney on Twitter and also askRodney on Telegram. Also, see further ways to get in touch with Rodney Lab. I post regularly on SvelteKit as well as other topics. Also subscribe to the newsletter to keep up-to-date with our latest projects.