# Formspree CLI

> Formspree Docs · Usando o Formspree CLI · 12 de novembro de 2024

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

O primeiro passo é criar um novo [projeto CLI](/articles/form-and-project-settings/getting-started-with-projects/) no dashboard do Formspree. Uma vez criado, você receberá um ID de projeto (Project ID) e uma chave de implantação (Deploy key).

![Screen\_Shot\_2020-10-26\_at\_10.22.37\_AM.png](/images/zendesk/8eed1ed3665831c6.png)

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.

```bash
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](https://nextjs.org/), segue um exemplo de como o arquivo top-level `_app.js` deve se parecer:

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

```shell
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 arquivo`formspree.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.

```javascript
{
  "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 arquivo`formspree.json` disponíveis, acesse: [Sobre o arquivo formspree.json](/articles/using-the-cli/the-formspree-json-file/)

### 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 ambiente`FORMSPREE_MAILCHIMP_APIKEY` que contém a chave de acesso ao serviço.

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

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

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

## Implantando formulários

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

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

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

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

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