Créer une liste d'attente avec Astro

Gardez la landing page pré-rendue et placez le travail serveur dans une Astro Action qui valide l'e-mail et le transmet à votre backend de formulaires avec une clé secrète. Un court script appelle l'action pour que le visiteur reste sur la page, et l'action classique du formulaire pointe vers une page rendue à la demande qui exécute la même action quand JavaScript n'est pas chargé.

Le guide principal a un court onglet Astro : une action, un formulaire et une page rendue à la demande. Cela fonctionne, mais renonce à ce pour quoi la plupart des gens choisissent Astro. Une landing page est la page que vous voulez le plus servir en HTML statique depuis un CDN, et une form action Astro l'oblige à être rendue à chaque requête. Cette page garde la landing page statique et ne déplace que l'inscription vers le serveur.

Ce qui change avec Astro

Astro pré-rend chaque page par défaut. Cela a deux effets sur une liste d'attente que les autres frameworks ne partagent pas :

La landing page ne peut donc ni utiliser le modèle de form action, ni lire ?ref= au build. La solution est de répartir les rôles : la page statique porte le formulaire et un script, l'action fait le travail serveur, et une petite page, /join, est rendue à la demande pour traiter un envoi qui arrive sans JavaScript.

Configurer le projet

La configuration côté produit, comme la création du formulaire et de la clé secrète, est dans le guide Astro de la documentation. Les fichiers de cette page :

src/
  actions/index.ts
  components/WaitlistForm.astro
  pages/index.astro
  pages/join.astro
  pages/thanks.astro
astro.config.mjs
.env

Un adaptateur et un secret typé

Les actions s'exécutent côté serveur au moment de la requête : le projet a donc besoin d'un adaptateur même si la plupart des pages restent statiques. astro add en installe un et modifie la configuration. Remplacez node par vercel, netlify ou cloudflare selon votre hébergeur.

npx astro add node

import { defineConfig, envField } from "astro/config";
import node from "@astrojs/node";

export default defineConfig({
  adapter: node({ mode: "standalone" }),
  env: {
    schema: {
      IKIFORM_SECRET_KEY: envField.string({ context: "server", access: "secret" }),
    },
  },
});

envField avec access: "secret" rend IKIFORM_SECRET_KEY importable uniquement depuis astro:env/server. Importez-la dans un script client et le build échoue, ce qui est le but. Créez la clé sous API keys avec le scope submissions:write.

IKIFORM_SECRET_KEY=ik_sk_your_secret_key

La définition des champs

L'action envoie email et ref. Si vous ajoutez une définition de champs dans l'onglet Fields du formulaire, elle doit lister les deux, sinon Ikiform refuse l'envoi avec 422 et unknown_field :

{
  "version": 1,
  "title": "Waitlist",
  "fields": [
    { "id": "email", "type": "email", "label": "Email", "required": true, "placeholder": "you@company.com" },
    { "id": "ref", "type": "text", "label": "Source", "validation": { "max_length": 40 } }
  ]
}

La construire

L'action du formulaire

import { ActionError, defineAction } from "astro:actions";
import { IKIFORM_SECRET_KEY } from "astro:env/server";
import { z } from "astro/zod";

const SOURCE = /^[a-z0-9_-]{1,40}$/;

export const server = {
  joinWaitlist: defineAction({
    accept: "form",
    input: z.object({
      email: z.email("Enter the email we should send your invite to."),
      ref: z
        .string()
        .nullish()
        .transform((value) => (value && SOURCE.test(value) ? value : "direct")),
      _gotcha: z.string().nullish(),
    }),
    handler: async (input, context) => {
      const origin = context.request.headers.get("origin");
      const response = await fetch("https://ikiform.com/f/frm_xxxxxxxxxxxxxxxx", {
        method: "POST",
        headers: {
          Accept: "application/json",
          "Content-Type": "application/json",
          Authorization: `Bearer ${IKIFORM_SECRET_KEY}`,
          ...(origin ? { Origin: origin } : {}),
        },
        body: JSON.stringify({
          email: input.email,
          ref: input.ref,
          _gotcha: input._gotcha ?? "",
        }),
        signal: AbortSignal.timeout(8000),
      }).catch(() => null);

      if (!response) {
        throw new ActionError({ code: "GATEWAY_TIMEOUT", message: "We couldn't reach the list. Try again." });
      }
      if (response.status === 429) {
        throw new ActionError({ code: "TOO_MANY_REQUESTS", message: "Lots of people are joining. Try again in a minute." });
      }
      const result = await response.json().catch(() => null);
      if (result?.ok) return { joined: true };
      throw new ActionError({
        code: "BAD_REQUEST",
        message: result?.error?.fields?.email?.[0] ?? result?.error?.message ?? "Couldn't join the list. Try again.",
      });
    },
  }),
};

• accept: "form" analyse le FormData. Les inputs vides arrivent en null : ref et le honeypot sont donc nullish(), et un ref absent devient direct.
• ref doit être composé de lettres minuscules, de chiffres, de - ou de _, jusqu'à 40 caractères. Tout le reste est stocké comme direct, pour qu'un lien forgé ne puisse pas remplir votre export de déchets. La limite correspond au max_length de la définition.
• z.email() est le schéma e-mail de premier niveau de Zod 4, exporté depuis astro/zod. Une adresse invalide échoue ici et n'atteint jamais Ikiform.
• Le navigateur envoie un en-tête Origin avec l'appel du script comme avec l'envoi classique. Ikiform s'en sert pour compter les soumissions de test gratuites et le fetch de l'action n'en envoie aucun : l'action le transmet donc.
• Le honeypot passe tel quel, Ikiform marque donc toujours comme spam les bots qui le remplissent. Les envois avec la clé secrète contournent la vérification humaine d'Ikiform : activer Spam check n'apporte donc rien ici ; c'est l'action qui fait office de garde-fou.
• Chaque échec lève une ActionError avec un code correspondant au problème. Le script et /join lisent tous deux error.message.

Le composant formulaire

---
interface Props {
  error?: string;
}

const { error = "" } = Astro.props;
---

<form method="POST" action="/join" data-waitlist>
  <label>
    Email
    <input name="email" type="email" autocomplete="email" required placeholder="you@company.com" />
  </label>
  <input type="hidden" name="ref" value="direct" />
  <input name="_gotcha" type="text" tabindex="-1" autocomplete="off" hidden />
  <p role="alert">{error}</p>
  <button>Join the waitlist</button>
</form>

<script>
  import { actions, isInputError } from "astro:actions";

  const query = new URLSearchParams(location.search);
  const source = (query.get("ref") ?? query.get("utm_source") ?? "").toLowerCase().slice(0, 40);

  for (const form of document.querySelectorAll<HTMLFormElement>("form[data-waitlist]")) {
    const ref = form.elements.namedItem("ref") as HTMLInputElement;
    const alert = form.querySelector<HTMLElement>("[role=alert]")!;
    const button = form.querySelector("button")!;
    if (source) ref.value = source;

    form.addEventListener("submit", async (event) => {
      event.preventDefault();
      button.disabled = true;
      button.textContent = "Joining";
      alert.textContent = "";

      const { error } = await actions.joinWaitlist(new FormData(form));
      if (!error) {
        const done = document.createElement("p");
        done.setAttribute("role", "status");
        done.textContent = "You're on the list. We'll email you on launch day.";
        form.replaceWith(done);
        return;
      }
      alert.textContent = isInputError(error) ? (error.fields.email?.[0] ?? "Check the address.") : error.message;
      button.disabled = false;
      button.textContent = "Join the waitlist";
    });
  }
</script>

• L'action du formulaire est /join, une URL normale. Sans JavaScript, le navigateur envoie là : le formulaire fonctionne donc avant le chargement du script ou si celui-ci échoue.
• Le script lit ?ref= dans le navigateur, car une page pré-rendue a été construite sans paramètres d'URL. Un visiteur venu de /?ref=newsletter est tagué newsletter.
• Astro inclut le <script> d'un composant une seule fois par page : la boucle branche donc chaque formulaire de liste d'attente de la page. Mettez-en un dans le hero et un dans le pied de page, et les deux fonctionnent.
• Le label englobe l'input au lieu de pointer vers un id, pour que deux copies sur une même page n'entrent pas en conflit.

La landing page et /join

---
import WaitlistForm from "../components/WaitlistForm.astro";
---

<main>
  <h1>Acme is almost here</h1>
  <p>Leave your email and we'll send you an invite the day it opens.</p>
  <WaitlistForm />
</main>

Pas d'export prerender, elle reste donc statique. /join s'en exclut et gère l'envoi classique :

---
import { actions, isInputError } from "astro:actions";
import WaitlistForm from "../components/WaitlistForm.astro";

export const prerender = false;

let error = "";
if (Astro.request.method === "POST") {
  const result = await Astro.callAction(actions.joinWaitlist, await Astro.request.formData());
  if (!result.error) return Astro.redirect("/thanks", 303);
  error = isInputError(result.error) ? (result.error.fields.email?.[0] ?? "Check the address.") : result.error.message;
  Astro.response.status = 400;
}
---

<main>
  <h1>Join the Acme waitlist</h1>
  <WaitlistForm error={error} />
</main>

Astro.callAction exécute l'action avec la même validation : il n'y a donc qu'un seul endroit à modifier. Le 303 envoie le navigateur vers /thanks en GET, une page statique que vous écrivez avec la même phrase de remerciement.

Notes de déploiement

Sur chaque hébergeur, la landing page et /thanks partent en fichiers statiques, et l'action plus /join deviennent une seule fonction serveur. Une journée calme ne coûte presque rien, et un pic de lancement touche surtout le CDN.

Vérifiez que tout fonctionne

1. Lancez astro dev et ouvrez http://localhost:4321/?ref=test. Inscrivez-vous. Le formulaire devient la phrase de remerciement sans rechargement.
2. Ouvrez Submissions dans le tableau de bord. L'inscription y est, avec ref à test.
3. Désactivez JavaScript dans le navigateur, rechargez et inscrivez-vous à nouveau. Vous arrivez sur /thanks, et la nouvelle inscription a ref à direct.
4. Envoyez not-an-email avec JavaScript désactivé. /join réaffiche le formulaire avec l'erreur sur l'e-mail.
5. Envoyez avec le honeypot rempli, _gotcha=bot. L'envoi reçoit quand même une réponse de succès, mais la soumission est stockée comme spam et n'envoie ni e-mail ni webhook.
6. Les envois depuis astro dev portent une origine localhost : ils comptent donc comme des soumissions de test. Ikiform n'a pas d'offre gratuite. Les tests sont gratuits : un espace de travail sans offre accepte 50 soumissions de test par mois depuis localhost. Pour passer en production, choisissez Pro à partir de 6 $/mois pour 500 soumissions, ou payez une seule fois : 10 000 soumissions pour 49 $ ou 50 000 soumissions pour 149 $, avec des crédits qui n'expirent jamais. Voir les tarifs.

Pièges

Questions