Die Formspree CLI

Die Formspree CLI bietet einen Workflow zum Erstellen und Bereitstellen von Formularen, der gut mit modernen JavaScript-Tools wie npm und React funktioniert. Formulare können automatisch mit CI/CD-Tools oder Plattformen wie Github, Vercel und Netlify bereitgestellt werden.

Dein Projekt einrichten

Hinweis: Die Formspree CLI unterstützt derzeit React-Formulare. Wir arbeiten an der Unterstützung für Vue und Vanilla JavaScript. Wenn du React nicht verwendest, kannst du Formspree trotzdem nutzen, indem du Formulare im Dashboard erstellst. Siehe dazu diesen Artikel zum Erstellen eines Dashboard-Projekts.

Der erste Schritt besteht darin, ein neues CLI-Projekt im Formspree-Dashboard zu erstellen. Nach der Erstellung siehst du eine Project ID und einen Deploy Key in den Settings deines Projekts:

Als Nächstes kannst du unsere React-Bibliothek verwenden, um dein neues Projekt mit deiner Frontend-App zu verbinden. Installiere zuerst die React-Bibliothek mit npm oder yarn.

npm install @formspree/react

Importiere dann FormspreeProvider und platziere ihn nahe der Spitze deiner Komponentenhierarchie, sodass er deine Formulare umschließt. Übergib dem FormspreeProvider deine oben erhaltene Projekt-ID.

Wenn du beispielsweise Next.js verwendest, könnte eine oberste _app.js-Datei so aussehen:

import { FormspreeProvider } from '@formspree/react';

function App({ Component, pageProps }) {
  return (
    <FormspreeProvider project="YOUR_PROJECT_ID">
      <Component {...pageProps} />
    </FormspreeProvider>
  );
}
export default App;

Jetzt bist du bereit, die Formspree CLI zu installieren und mit dem Erstellen von Formularen zu beginnen.

Die CLI installieren

Führe zum Einstieg die folgenden Befehle aus, um die Formspree-Befehlszeilenschnittstelle zu installieren und dein Projekt zu initialisieren:

npm i -g @formspree/cli
formspree init

Dadurch wird eine leere Datei formspree.json im Stammverzeichnis deines Projekts erstellt. Hier konfigurierst du deine Formulare.

Form-Endpoints erstellen

Das Erstellen von Formularen mit der Formspree CLI erfolgt durch Bearbeiten der Datei formspree.json. Diese Datei enthält eine Liste von Form-Keys und zugehörigen Konfigurationen. Hier ist ein Beispiel für die Konfiguration eines Newsletter-Opt-in-Formulars, das Abonnenten zu einer Mailchimp-Liste anmeldet:

{
  "forms": {
    "signupForm": {
      "name": "Sign-Up Form",
      "actions": [{ 
        "app": "mailchimp", 
        "type": "addOrUpdateContact", 
        "apiKey": "$FORMSPREE_MAILCHIMP_APIKEY" 
      }]
    }
  }
}

Eine ausführlichere Erläuterung der verschiedenen Konfigurationsoptionen findest du in der formspree.json-Referenz hier: Die formspree.json-Datei

Umgebungsvariablen

Viele Formularaktionen, wie Mailchimp und ConvertKit, erfordern Zugriffsschlüssel zur Authentifizierung. Diese Schlüssel sollten nicht in Konfigurationsdateien gespeichert werden, die in die Versionsverwaltung eingecheckt werden. Stattdessen können diese Variablen in der Umgebung aufbewahrt und von der Formspree CLI nur während des Deployments abgerufen werden.

Du kannst in formspree.json mit der $-Notation auf Umgebungsvariablen verweisen. Im obigen Anmeldeformular-Beispiel verweist das Mailchimp-Plugin auf einen API-Key, der in der Umgebungsvariablen FORMSPREE_MAILCHIMP_APIKEY gespeichert ist.

        ...
        "apiKey": "$FORMSPREE_MAILCHIMP_APIKEY" 
        ...

Zur Vereinfachung prüft die Formspree CLI auf Umgebungsvariablen, die in einer .env-Datei definiert sind, bevor sie die Umgebung durchsucht. Wenn du eine .env-Datei verwendest, denke daran: Committe deine .env-Datei nicht in die Versionsverwaltung.

Formulare mit React erstellen

Zum Erstellen eines Formulars kannst du den useForm-Hook aus der formspree-react-Bibliothek verwenden. Er stellt Funktionen zum Verarbeiten von Formularübermittlungen und zum Verwalten des Formularzustands bereit.

Initialisiere das Formular in React, indem du useForm aufrufst und den Form-Key übergibst, den du in der Datei formspree.json verwendet hast.

const [state, handleSubmit] = useForm('{form-key}');

So könnte eine Formularkomponente für den oben erstellten signupForm-Endpoint aussehen:

import { useForm } from '@formspree/react';

function SignupForm() {
  const [state, handleSubmit] = useForm('signupForm');
  if (state.succeeded) {
    return <div>Thank you for signing up!</div>;
  }
  return (
    <form onSubmit={handleSubmit}>
      <label htmlFor="email">Email</label>
      <input id="email" type="email" name="email" />
      <button type="submit" disabled={state.submitting}>Sign up</button>
    </form>
  )
}

Weitere Informationen zum Erstellen von Formularen mit React findest du im Artikel zur Formspree-React-Bibliothek.

Formulare bereitstellen

Um die Änderungen an deiner Datei formspree.json anzuwenden, führe den Deploy-Befehl aus:

formspree deploy -k <your-deploy-key>

Deinen Deploy-Key findest du im Tab „Settings“ deines Projekts in Formspree.
Anstatt jedes Mal das Flag -k zu verwenden, kannst du eine .env-Datei im Stammverzeichnis deines Projekts erstellen und eine Umgebungsvariable definieren:

echo "FORMSPREE_DEPLOY_KEY=<your-deploy-key>" >> .env
echo ".env" >> .gitignore

Committe deine .env-Datei nicht in die Versionsverwaltung.

Du solltest deinen Deploy-Key wie jedes andere geheime Token behandeln. Eine gängige Konvention ist das Erstellen einer .env.example-Datei (ohne den tatsächlichen Key), die Entwickler als Vorlage verwenden können:

echo "FORMSPREE_DEPLOY_KEY=" >> .env.example

Continuous Deployment

Das Bereitstellen deiner Formulare in einer Produktionsumgebung folgt denselben Prinzipien wie das lokale Bereitstellen. Der Hauptunterschied besteht darin, dass du diese Variablen in deinen Deployment-Einstellungen konfigurieren musst, anstatt eine .env-Datei für deine Umgebungsvariablen zu verwenden.

Die Umgebungsvariablen sollten mit den $-Variablennamen übereinstimmen, die du in deiner formspree.json-Konfiguration definiert hast, mit Ausnahme von FORMSPREE_DEPLOY_KEY, das von formspree deploy benötigt wird.

In GitHub kannst du beispielsweise Secrets zu deinen Repository-Einstellungen hinzufügen und sie dann in deinem Workflow wie folgt als Umgebungsvariablen referenzieren:

steps:
  - shell: bash
    env: 
      - FORMSPREE_DEPLOY_KEY: ${{ secrets.FormspreeDeployKey }}
      - FORMSPREE_MAILCHIMP_APIKEY: ${{ secrets.MailchimpAPIKey }}
    run: formspree deploy