# Le CLI Formspree

> Formspree Docs · Utiliser le CLI · 12 novembre 2024

Le CLI Formspree offre un workflow pour créer et déployer des formulaires, parfaitement adapté aux outils JavaScript modernes comme npm et React. Les formulaires peuvent être déployés automatiquement via des outils ou des plateformes de CI/CD comme GitHub, Vercel et Netlify.

## Configurer votre projet

_Remarque : le CLI Formspree prend actuellement en charge les formulaires React. Nous travaillons à l'ajout du support pour Vue et JavaScript vanilla. Si vous n'utilisez pas React, vous pouvez toujours utiliser Formspree en créant des formulaires depuis le tableau de bord. Consultez cet article sur la [création d'un projet tableau de bord](/articles/form-and-project-settings/getting-started-with-projects/)._

La première étape consiste à créer un nouveau [projet CLI](/articles/form-and-project-settings/getting-started-with-projects/) dans le tableau de bord Formspree. Une fois créé, vous verrez un identifiant de projet (Project ID) et une clé de déploiement (Deploy Key) dans les **paramètres** de votre projet :

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

Ensuite, vous pouvez utiliser notre bibliothèque React pour connecter votre nouveau projet à votre application front-end. Commencez par installer la bibliothèque React via npm ou yarn.

```
npm install @formspree/react
```

Importez ensuite `FormspreeProvider` et placez-le en haut de votre hiérarchie de composants, en englobant vos formulaires. Fournissez à `FormspreeProvider` votre identifiant de projet obtenu ci-dessus.

Par exemple, si vous utilisez [Next.js](https://nextjs.org/), voici à quoi pourrait ressembler un fichier `_app.js` de niveau supérieur :

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

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

Vous êtes maintenant prêt à installer le CLI Formspree et à commencer à créer des formulaires.

## Installer le CLI

Pour démarrer, exécutez les commandes suivantes afin d'installer l'interface en ligne de commande Formspree et d'initialiser votre projet :

```shell
npm i -g @formspree/cli
formspree init
```

Cela créera un fichier `formspree.json` vide à la racine de votre projet. C'est dans ce fichier que vous configurerez vos formulaires.

## Créer des points d'entrée de formulaire

La création de formulaires avec le CLI Formspree s'effectue en modifiant le fichier `formspree.json`. Ce fichier contient une liste de clés de formulaire et leurs configurations associées. Voici un exemple de configuration d'un formulaire d'inscription à une newsletter qui inscrit des abonnés à une liste Mailchimp :

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

Pour une explication plus approfondie des différentes options de configuration, consultez la référence `formspree.json` ici : [Le fichier formspree.json](/articles/using-the-cli/the-formspree-json-file/)

### Variables d'environnement

De nombreuses actions de formulaire, comme Mailchimp et ConvertKit, nécessitent des clés d'accès pour l'authentification. Ces clés ne doivent pas être enregistrées dans des fichiers de configuration versionnés. À la place, ces variables peuvent être conservées dans l'environnement et lues par le CLI Formspree uniquement lors du déploiement.

Vous pouvez référencer des variables d'environnement dans `formspree.json` en utilisant la notation `$`. Dans l'exemple du formulaire d'inscription ci-dessus, le plugin Mailchimp fait référence à une clé API stockée dans la variable d'environnement `FORMSPREE_MAILCHIMP_APIKEY`.

```javascript
        ...
        "apiKey": "$FORMSPREE_MAILCHIMP_APIKEY" 
        ...
```

Par commodité, le CLI Formspree vérifie d'abord les variables d'environnement définies dans un fichier `.env` avant de chercher dans l'environnement. Si vous utilisez un fichier `.env`, n'oubliez pas : **ne commitez pas votre fichier `.env` dans le contrôle de version.**

## Créer des formulaires avec React

Pour créer un formulaire, vous pouvez utiliser le hook `useForm` de la bibliothèque `formspree-react`. Il expose des fonctions pour gérer les soumissions de formulaires et l'état du formulaire.

Initialisez le formulaire dans React en appelant `useForm` et en passant la clé de formulaire que vous avez utilisée dans le fichier `formspree.json`.

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

Voici à quoi pourrait ressembler un composant de formulaire pour le point d'entrée `signupForm` que nous avons créé ci-dessus :

```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>
  )
}
```

Pour plus d'informations sur la création de formulaires avec React, consultez l'article sur la [bibliothèque React Formspree](/articles/working-with-react/the-formspree-react-library/).

## Déployer des formulaires

Pour appliquer les modifications apportées à votre fichier `formspree.json`, exécutez la commande de déploiement :

```shell
formspree deploy -k <your-deploy-key>
```

Votre clé de déploiement est disponible dans l'onglet « Settings » de votre projet Formspree.  
Au lieu d'utiliser le flag `-k` à chaque fois, vous pouvez créer un fichier `.env` à la racine de votre projet et définir une variable d'environnement :

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

**Ne commitez pas votre fichier `.env` dans le contrôle de version.**

Traitez votre clé de déploiement comme tout autre jeton secret. Une convention courante consiste à créer un fichier `.env.example` (sans la vraie clé) que les développeurs peuvent utiliser comme modèle :

```shell
echo "FORMSPREE_DEPLOY_KEY=" >> .env.example
```

### Déploiement continu

Le déploiement de vos formulaires en environnement de production suit les mêmes principes qu'en local. La principale différence est que, plutôt que d'utiliser un fichier `.env` pour vos variables d'environnement, vous devez les configurer dans les paramètres de votre plateforme de déploiement.

Les variables d'environnement doivent correspondre aux noms de variables `$` que vous avez définis dans votre configuration `formspree.json`, à l'exception de `FORMSPREE_DEPLOY_KEY` qui est nécessaire pour `formspree deploy`.

Par exemple, dans GitHub, vous pouvez ajouter des secrets aux paramètres de votre dépôt, puis les référencer comme variables d'environnement dans votre workflow :

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