# Die Formspree CLI

> Formspree Docs · Die CLI verwenden · 12. November 2024

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](/articles/form-and-project-settings/getting-started-with-projects/)._ 

Der erste Schritt besteht darin, ein neues [CLI-Projekt](/articles/form-and-project-settings/getting-started-with-projects/) im Formspree-Dashboard zu erstellen. Nach der Erstellung siehst du eine Project ID und einen Deploy Key in den **Settings** deines Projekts:

**![CLI guide 2.png](/images/zendesk/bab3b66ed902465e.png)**

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](https://nextjs.org/) verwendest, könnte eine oberste `_app.js`-Datei so aussehen:

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

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

```javascript
{
  "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](/articles/using-the-cli/the-formspree-json-file/)

### 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.

```javascript
        ...
        "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.

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

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

```jsx
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](/articles/working-with-react/the-formspree-react-library/).

## Formulare bereitstellen

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

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

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

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

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