La Formspree CLI

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.

Il primo passo è creare un nuovo progetto CLI nella dashboard di Formspree. Una volta creato, vedrai un Project ID e una Deploy Key nelle Impostazioni del tuo progetto:

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, ecco come potrebbe apparire un file _app.js di alto livello:

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:

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:

{
  "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

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.

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

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

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

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.

Deployare i moduli

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

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:

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:

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:

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