Formspree CLI — Formspree Docs

Formspree CLI は、npm や React などのモダンな JavaScript ツールと連携するフォームのビルドおよびデプロイワークフローを提供します。フォームは、Github、Vercel、Netlify などの CI/CD ツールやプラットフォームを使用して自動的にデプロイできます。

プロジェクトのセットアップ

注意：Formspree CLI は現在 React フォームをサポートしています。Vue およびバニラ JavaScript のサポートに向けて取り組んでいます。React を使用していない場合でも、ダッシュボードでフォームを作成することで Formspree を利用できます。ダッシュボードプロジェクトの作成に関するこちらの記事をご覧ください。

最初のステップは、Formspreeダッシュボードで新しい CLI プロジェクトを作成することです。作成後、プロジェクトの Settings にプロジェクトIDとデプロイキーが表示されます：

次に、React ライブラリを使用して新しいプロジェクトをフロントエンドアプリに接続できます。まず、npm または yarn を使用して React ライブラリをインストールします。

npm install @formspree/react

次に、FormspreeProvider をインポートして、コンポーネント階層の上部近くに配置し、フォームをラップします。上記で取得したプロジェクトIDを FormspreeProvider に渡します。

たとえば、Next.js を使用している場合、トップレベルの _app.js ファイルは次のようになります：

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

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

これで、Formspree CLI をインストールしてフォームを作成する準備が整いました。

CLI のインストール

はじめに、以下のコマンドを実行して Formspree コマンドラインインターフェースをインストールし、プロジェクトを初期化します：

npm i -g @formspree/cli
formspree init

これにより、プロジェクトのルートに空の formspree.json ファイルが作成されます。ここでフォームの設定を行います。

フォームエンドポイントの作成

Formspree CLI でフォームを作成するには、formspree.json ファイルを編集します。このファイルにはフォームキーと関連する設定のリストが含まれます。以下は、Mailchimp リストに購読者を登録するニュースレターオプトインフォームの設定例です：

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

さまざまな設定オプションの詳細については、こちらの formspree.json リファレンスをご覧ください：formspree.json ファイル

環境変数

Mailchimp や ConvertKit などの多くのフォームアクションは、認証のためにアクセスキーを必要とします。これらのキーはバージョン管理にチェックインされる設定ファイルに保存すべきではありません。代わりに、これらの変数を環境に保持し、デプロイ時にのみ Formspree CLI からアクセスさせることができます。

formspree.json では $ 記法を使って環境変数を参照できます。上記のサインアップフォームの例では、Mailchimp プラグインが FORMSPREE_MAILCHIMP_APIKEY 環境変数に格納された API キーを参照しています。

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

便宜上、Formspree CLI は環境を検索する前に .env ファイルで定義された環境変数を確認します。.env ファイルを使用する場合は、.env ファイルをバージョン管理にコミットしないでください。

React でフォームを構築する

フォームを構築するには、formspree-react ライブラリの useForm フックを使用できます。これにより、フォーム送信の処理とフォームの状態管理のための関数が提供されます。

formspree.json ファイルで使用したフォームキーを渡して useForm を呼び出し、React でフォームを初期化します。

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

先ほど作成した signupForm エンドポイントのフォームコンポーネントの例は次のとおりです：

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

React でのフォーム作成の詳細については、Formspree React ライブラリに関する記事をご覧ください。

フォームのデプロイ

formspree.json ファイルへの変更を適用するには、デプロイコマンドを実行します：

formspree deploy -k <your-deploy-key>

デプロイキーは Formspree のプロジェクトの「Settings」タブで確認できます。
毎回 -k フラグを使用する代わりに、プロジェクトのルートに .env ファイルを作成して環境変数を定義できます：

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

.env ファイルをバージョン管理にコミットしないでください。

デプロイキーは他のシークレットトークンと同様に扱うべきです。一般的な慣習として、開発者がテンプレートとして使用できる .env.example ファイル（実際のキーを除く）を作成することが推奨されます：

echo "FORMSPREE_DEPLOY_KEY=" >> .env.example

継続的デプロイ

本番環境でフォームをデプロイする手順は、ローカルでのデプロイと基本的に同じです。主な違いは、環境変数に .env ファイルを使用するのではなく、デプロイ設定でそれらの変数を設定する必要があることです。

環境変数は formspree.json 設定で定義した $ 変数名と一致させる必要があります。ただし、formspree deploy に必要な FORMSPREE_DEPLOY_KEY は例外です。

たとえば、GitHub ではリポジトリ設定にシークレットを追加し、次のようにワークフローで環境変数として参照できます：

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