El CLI de Formspree

El CLI de Formspree ofrece un flujo de trabajo para construir y desplegar formularios que funciona perfectamente con herramientas modernas de JavaScript como npm y React. Los formularios pueden desplegarse automáticamente usando herramientas de CI/CD o plataformas como Github, Vercel y Netlify.

Configurar tu proyecto

Nota: el CLI de Formspree actualmente soporta formularios React. Estamos trabajando en el soporte para Vue y JavaScript puro. Si no estás usando React, todavía puedes usar Formspree creando formularios en el panel. Consulta este artículo sobre crear un proyecto en el panel.

El primer paso es crear un nuevo proyecto CLI en el panel de Formspree. Una vez creado, verás un Project ID y un Deploy Key en los Settings de tu proyecto:

A continuación, puedes usar nuestra biblioteca de React para conectar tu nuevo proyecto con tu aplicación front-end. Primero instala la biblioteca de React usando npm o yarn.

npm install @formspree/react

Luego importa FormspreeProvider y colócalo cerca de la parte superior de la jerarquía de tus componentes, envolviendo tus formularios. Proporciona al FormspreeProvider el ID de proyecto que obtuviste anteriormente.

Por ejemplo, si estás usando Next.js, así podría verse un archivo _app.js de nivel superior:

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

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

Ahora estás listo para instalar el CLI de Formspree y comenzar a crear formularios.

Instalar el CLI

Para empezar, ejecuta los siguientes comandos para instalar la interfaz de línea de comandos de Formspree e inicializar tu proyecto:

npm i -g @formspree/cli
formspree init

Esto creará un archivo formspree.json vacío en la raíz de tu proyecto. Aquí es donde configurarás tus formularios.

Crear endpoints de formulario

Crear formularios con el CLI de Formspree se hace editando el archivo formspree.json. Este archivo contiene una lista de claves de formulario y sus configuraciones asociadas. Aquí tienes un ejemplo de configuración de un formulario de suscripción a un boletín que registra suscriptores en una lista de Mailchimp:

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

Para una explicación más detallada de las distintas opciones de configuración, consulta la referencia de formspree.json aquí: El archivo formspree.json

Variables de entorno

Muchas acciones de formulario, como Mailchimp y ConvertKit, requieren claves de acceso para autenticarse. Estas claves no deberían guardarse en archivos de configuración que se suben al control de versiones. En su lugar, estas variables pueden mantenerse en el entorno y ser leídas por el CLI de Formspree únicamente durante el despliegue.

Puedes referenciar variables de entorno en formspree.json usando la notación $. En el ejemplo anterior del formulario de suscripción, el plugin de Mailchimp hace referencia a una clave de API almacenada en la variable de entorno FORMSPREE_MAILCHIMP_APIKEY.

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

Como conveniencia, el CLI de Formspree buscará variables de entorno definidas en un archivo .env antes de buscar en el entorno. Si usas un archivo .env, recuerda: no subas tu archivo .env al control de versiones.

Construir formularios con React

Para construir un formulario, puedes usar el hook useForm de la biblioteca formspree-react. Este expone funciones para manejar los envíos de formulario y gestionar el estado del formulario.

Inicializa el formulario en React llamando a useForm y pasando la clave de formulario que usaste en el archivo formspree.json.

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

Así podría verse un componente de formulario para el endpoint signupForm que creamos arriba:

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

Para más información sobre cómo crear formularios con React, consulta el artículo sobre la biblioteca React de Formspree.

Desplegar formularios

Para aplicar los cambios que hagas en tu archivo formspree.json, ejecuta el comando de despliegue:

formspree deploy -k <your-deploy-key>

Tu deploy key se encuentra en la pestaña “Settings” de tu proyecto en Formspree.
En lugar de usar la flag -k cada vez, puedes crear un archivo .env en la raíz de tu proyecto y definir una variable de entorno:

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

No subas tu archivo .env al control de versiones.

Debes tratar tu deploy key como cualquier otro token secreto. Una convención común es crear un archivo .env.example (sin la clave real) que los desarrolladores puedan usar como plantilla:

echo "FORMSPREE_DEPLOY_KEY=" >> .env.example

Despliegue continuo

Desplegar tus formularios en un entorno de producción sigue los mismos principios que desplegar localmente. La principal diferencia es que, en lugar de usar un archivo .env para tus variables de entorno, debes configurar esas variables en los ajustes de despliegue.

Las variables de entorno deben coincidir con los nombres de variables con $ que has definido en tu configuración de formspree.json, con la excepción de FORMSPREE_DEPLOY_KEY que es necesaria para formspree deploy.

Por ejemplo, en GitHub puedes añadir Secrets a la configuración de tu repositorio y luego referenciarlos como variables de entorno en tu workflow así:

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