# La Formspree CLI

> Formspree Docs · Usare la CLI · 12 novembre 2024

La Formspree CLI offre un flusso di lavoro per la creazione e il deployment di moduli che si integra bene con i moderni strumenti JavaScript come npm e React. I moduli possono essere deployati automaticamente usando strumenti CI/CD o piattaforme come Github, Vercel e Netlify.

## Configurare il tuo progetto

_Nota: la Formspree CLI attualmente supporta i moduli React. Stiamo lavorando al supporto per Vue e JavaScript vanilla. Se non usi React, puoi comunque usare Formspree creando moduli nella dashboard. Consulta questo articolo su come [creare un progetto dalla dashboard](/articles/form-and-project-settings/getting-started-with-projects/)._ 

Il primo passo è creare un nuovo [progetto CLI](/articles/form-and-project-settings/getting-started-with-projects/) nella dashboard di Formspree. Una volta creato, vedrai un Project ID e una Deploy Key nelle **Impostazioni** del tuo progetto:

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

Successivamente, puoi usare la nostra libreria React per connettere il tuo nuovo progetto alla tua app front-end. Per prima cosa installa la libreria react usando npm o yarn.

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

Poi importa `FormspreeProvider` e posizionalo in cima alla gerarchia dei tuoi componenti, avvolgendo i tuoi moduli. Fornisci a `FormspreeProvider` il project ID ottenuto sopra.

Ad esempio, se stai usando [Next.js](https://nextjs.org/), ecco come potrebbe apparire un file `_app.js` di alto livello:

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

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

Ora sei pronto per installare la Formspree CLI e iniziare a creare moduli.

## Installare la CLI

Per iniziare, esegui i seguenti comandi per installare l'interfaccia a riga di comando di Formspree e inizializzare il tuo progetto:

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

Questo creerà un file `formspree.json` vuoto nella root del tuo progetto. È qui che configurerai i tuoi moduli.

## Creare gli endpoint dei moduli

La creazione di moduli con la Formspree CLI si effettua modificando il file `formspree.json`. Questo file contiene un elenco di chiavi dei moduli e le relative configurazioni. Ecco un esempio di configurazione di un modulo di iscrizione a una newsletter che iscrive gli abbonati a una lista Mailchimp:

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

Per una spiegazione più approfondita delle varie opzioni di configurazione consulta il riferimento di `formspree.json` qui: [Il file formspree.json](/articles/using-the-cli/the-formspree-json-file/)

### Variabili d'ambiente

Molte azioni dei moduli, come Mailchimp e ConvertKit, richiedono chiavi di accesso per l'autenticazione. Queste chiavi non dovrebbero essere salvate in file di configurazione che vengono inclusi nel controllo di versione. Invece, queste variabili possono essere conservate nell'ambiente e accessibili dalla Formspree CLI solo durante il deployment.

Puoi fare riferimento alle variabili d'ambiente in `formspree.json` usando la notazione `$`. Nell'esempio del modulo di iscrizione sopra, il plugin Mailchimp fa riferimento a un'API key memorizzata nella variabile d'ambiente `FORMSPREE_MAILCHIMP_APIKEY`.

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

Per comodità, la Formspree CLI controllerà le variabili d'ambiente definite in un file `.env` prima di cercare nell'ambiente. Se usi un file `.env`, ricorda solo: **non includere il tuo file `.env` nel controllo di versione.**

## Creare moduli con React

Per creare un modulo, puoi usare l'hook `useForm` della libreria `formspree-react`. Espone funzioni per gestire gli invii dei moduli e gestire lo stato del modulo.

Inizializza il modulo in React chiamando `useForm` e passando la chiave del modulo che hai usato nel file `formspree.json`.

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

Ecco come potrebbe apparire un componente modulo per l'endpoint `signupForm` che abbiamo creato sopra:

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

Per maggiori informazioni sulla creazione di moduli con React consulta l'articolo sulla [libreria React di Formspree](/articles/working-with-react/the-formspree-react-library/).

## Deployare i moduli

Per applicare le modifiche che apporti al tuo file `formspree.json`, esegui il comando deploy:

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

La tua deploy key si trova nella scheda "Settings" del progetto in Formspree.  
Invece di usare il flag `-k` ogni volta, puoi creare un file `.env` nella root del tuo progetto e definire una variabile d'ambiente:

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

**Non includere il tuo file `.env` nel controllo di versione.**

Dovresti trattare la tua deploy key come qualsiasi altro token segreto. Una convenzione comune è creare un file `.env.example` (escludendo la chiave effettiva) che gli sviluppatori possono usare come template:

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

### Continuous Deployment

Il deployment dei tuoi moduli in un ambiente di produzione segue gli stessi principi del deployment in locale. La differenza principale è che, invece di usare un file `.env` per le tue variabili d'ambiente, devi configurare quelle variabili nelle impostazioni del tuo deployment.

Le variabili d'ambiente dovrebbero corrispondere ai nomi delle variabili `$` che hai definito nella tua configurazione `formspree.json`, con l'eccezione di `FORMSPREE_DEPLOY_KEY` che è necessaria per `formspree deploy`.

Ad esempio, in GitHub puoi aggiungere Secrets alle impostazioni del tuo repository e poi farvi riferimento come variabili d'ambiente nel tuo workflow in questo modo:

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