The Formspree CLI

The Formspree CLI offers a workflow for building and deploying forms that works nicely with modern JavaScript tools like npm and React. Forms can be deployed automatically using CI/CD tools or platforms like Github, Vercel and Netlify.

A Quick Example

Suppose you want to add a newsletter sign-up form to your website using the Formspree CLI. The first step is to create a new CLI project in the Formspree dashboard. You'll see a Project ID and a Deploy Key.

Screen_Shot_2020-10-26_at_10.22.37_AM.png

Next, you can use our React library to connect your new project to your front-end app. To do that import a FormspreeProvider and put it near the top of your component hierarchy, wrapping your forms. Supply the FormspreeProvider with your project ID.

For example, if you are using Next.js, here's what your top-level _app.js file might look like:

import { FormspreeProvider } from '@formspree/react';
function App({ Component, pageProps }) {
  return (
    <FormspreeProvider project="YOUR_PROJECT_ID">
      <Component {...pageProps} />
    </FormspreeProvider>
  );
}
export default App;

Once you've got your project connected, you can create a formspree.json at your project root, and add a new form configuration like this:

{
  "forms": {
    "signupForm": {
      "name": "Sign-up Form",
      "actions": [{ "app": "mailchimp", "type": "addOrUpdateContact" }]
    }
  }
}

Now that you've set up a project, and your form, it's time to build the form component. You can put your form component anywhere on your site, as long as the component is a child of your FormspreeProvider.

To build a form, use the useForm hook to handle form submissions, and manage form state. Here's what a form component might look like:

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

This javascript code is responsible for rendering the form and any needed inputs. Each input should have a name attribute. The @formspree/react library takes care of sending the data to Formspree.

Finally, the formspree.json file can be deployed to the Formspree server, updating your live forms to match the config file. To do so, run this command:

formspree deploy

The command can be run from your local machine, or during the build phase in your production environment.

Installing the CLI

To get started, run the following commands to install the Formspree command line interface and initialize your project:

npm i -g @formspree/cli
formspree init

This will create an empty formspree.json file in the root of your project. This is where you will configure your forms.

Configuring Forms

Configuring your forms is accomplished by editing the formspree.json file. This file contains a list of form keys and associated configurations. Here’s an example of a newsletter opt-in form configuration that signs up subscribers to a Mailchimp list:

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

For a more in-depth explanation of the various configuration options see the formspree.json reference here: The formspree.json File

Environment Variables

Many form actions, such as Mailchimp and ConvertKit, require access keys for authentication. These keys should not be saved in configuration files that are checked into version control. Instead, these variables can be kept in the environment, and accessed by the Formspree CLI only during deployment.

You can refer to environment variables in formspree.json by using $ notation. In the sign-up form example above, the Mailchimp plugin refers to an API key stored in the FORMSPREE_MAILCHIMP_APIKEY environment variable.

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

As a convenience, the Formspree CLI will check for environment variables defined in a .env file before searching the environment. If you use a .env file, just remember, do not commit your .env file to version control.

Deploying Forms

To apply the changes you make to your formspree.json file, run the deploy command:

formspree deploy -k <your-deploy-key>

Your deploy key can be found under the project’s “Settings” tab in Formspree.
Instead of using the -k flag every time, you can create a .env file in the root of your project and define an environment variable:

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

Do not commit your .env file to version control.

You should treat your deploy key like any other secret token. A common convention is to create a .env.example file (excluding the actual key) that developers can use as a template:

echo "FORMSPREE_DEPLOY_KEY=" >> .env.example

Continuous Deployment

Deploying your forms in a production environment follows the same principles as deploying locally. The main difference is, rather than using a .env file for your environment variables, you must configure those variables in your deployment settings.

Environment variables should match the $ variable names you’ve defined in your formspree.json configuration, with the exception of the FORMSPREE_DEPLOY_KEY which is needed by formspree deploy.

For example, in GitHub you can add Secrets to your repository settings, and then refer to them as environment variables in your workflow like this:

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

Using the CLI