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