Formspree CLI

O Formspree CLI oferece um workflow para construir e implantar formulários que trabalhem com tecnologias JavaScript modernas como npm e React. Formulários podem ser implantados automaticamente utilizando ferramentas de CI/CD ou através de platafaromas como Github, Vercel e Netlify

Configura seu projeto

Nota: O cliente Formspree atualmente suporta formulários React. Estamos trabalhando em novas integrações como Vue e vanilla JavaScript. Se você não esta utilizando React, ainda assim é possível criar seus formulários no dashboard do Formspree. Saiba mais em criando projetos dashboard. 

O primeiro passo é criar um novo projeto CLI no dashboard do Formspree. Uma vez criado, você receberá um ID de projeto (Project ID) e uma chave de implantação (Deploy key).

Em seguida, você pode usar nossa biblioteca React para conectar o seu novo projeto com seu app front-end. Primeiro instale a biblioteca utilizando o npm ou o yarn.

npm install @formspree/react

Importe FormspreeProvider e coloque próximo ao top-level na hierarquia dos seus componentes, englobando seus formulários. Adicionei ao FormspreeProvider o seu ID de projeto (Project ID).

Por exemplo, se estiver utilizando Next.js, segue um exemplo de como o arquivo top-level _app.js deve se parecer:

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

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

Feito isso, você está pronto para instalar o Formpsree CLI e criar formulários

Instalando o CLI

Para começar, execute os seguintes comandos para instalar o Formspree client line interface (cliente Formspree) e inicializar seu projeto.

npm i -g @formspree/cli
formspree init

Esses comandos criaram um arquivo vaziao chamado formspree.json na raiz do seu projeto. Neste arquivo você configurará os seus formulários.

Criando Formulários

Para criar formulários utilizando o Formspree CLI basta editar o arquivoformspree.json. Esse arquivo contém uma lista de chaves de formulários associados a suas configurações. Segue um exemplo de um formulário de Newsletters que cadastra assinantes a uma lista do Mailchimp.

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

Saiba mais sobre as opções de configuração do arquivoformspree.json disponíveis, acesse: Sobre o arquivo formspree.json

Variáveis de ambiente

Várias açoes de formulário como Mailchimp e ConvertKit, necessitam de chaves de acesso para autenticação. Essas chaves não devem ser salvas nos arquivos de configuração que são enviados para um sistema de versionamento como Git. Essas chaves devem ser mantidas no ambiente e acessadas pelo Formspree CLI apenas durante a implantação.

Você podem referenciar as chaves no arquivo formspree.json utilizando a notação $ como prefixo. No exemplo acima, o plugin Mailchimp utiliza a variável de ambienteFORMSPREE_MAILCHIMP_APIKEY que contém a chave de acesso ao serviço.

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

Por padrão, o Formspree CLI verifica as variáveis de ambiente definidas no arquivo .env. Se você utiliza o arquivo .env, lembre-se, não envie o arquivo .env para seus sistema de versionamento tal como Git.

Construindo formulários com React

Para construir um formulário, você pode utilizar o  useForm hook da biblioteca formspree-react. Esse hook fornece funções para trabalhar com submissões e controlar o estado do formulário

Inicialize o formulário em React chamando useForm definindo a chave de formulário utilizada no arquivo formspree.json.

const [state, handleSubmit] = useForm('{chave-do-formulario}');

Abaixo um exemplo de como o componente de formulário deve se parecer para o signupForm endpoint criado acima:

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

function SignupForm() {
  const [state, handleSubmit] = useForm('signupForm');
  if (state.succeeded) {
    return <div>Obrigado por se cadastrar!</div>;
  }
  return (
    <form onSubmit={handleSubmit}>
      <label htmlFor="email">Email</label>
      <input id="email" type="email" name="email" />
      <button type="submit" disabled={state.submitting}>Cadastrar</button>
    </form>
  )
}

Para mais informações sobre como criar formulários com react, veja o artigo em Biblioteca Formspree React.

Implantando formulários

Para aplicar as mudanças feitas no arquivo formspree.json, execute o comando de implantação:

formspree deploy -k <sua-chave-de-implantacao>

Sua chave de implantação pode ser encontrada na aba "Settings" do seu projeto no Formspree.
Ao invés de usar a flag-k todas as vezes que executar o comando de implantação, você pode criar um arquiv .env na raiz do seu projeto e definir uma variável de ambiente para o a chave de implantação:

echo "FORMSPREE_DEPLOY_KEY=<sua-chave-de-implantacao>" >> .env
echo ".env" >> .gitignore

Não envie seu arquivo .env para sistemas de versionamento.

Você deve tratar sua chave de implantação como qualquer outra chave secreta. Uma prática comum é criar um arquiv .env.example (excluindo as chaves verdades) para que os desenvolvedores possam usar como template:

echo "FORMSPREE_DEPLOY_KEY=" >> .env.example

Implantação contínuia (Continous deployment)

Implantar seus formulários em um ambiente de produção segue os mesmos princípios de implantar localmente. A principal diferença é: ao invés de utilizar o arquivo .env file para suas variáveis de ambinte, você deve definir essas variáveis na sua configuração de implantação.

As variáveis de ambiente devem corresponder às variáveis prefixadas com $ que você definiu no arquivo formspree.json, com exceção da variável FORMSPREE_DEPLOY_KEY que no caso, é utilizada pelo comando formspree deploy.

Por exemplo, no GitHub você pode adicionar chaves secretas na opção Secrets do seu repositório, e então referenciar as chaves como variáveis de ambiente no seu workflow como no exemplo abaixo:

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