# Formspree CLI

> Formspree Docs · CLIの使用方法 · 2024年11月12日

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

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

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

最初のステップは、Formspreeダッシュボードで新しい [CLI プロジェクト](/articles/form-and-project-settings/getting-started-with-projects/)を作成することです。作成後、プロジェクトの **Settings** にプロジェクトIDとデプロイキーが表示されます：

**![CLI guide 2.png](/images/zendesk/bab3b66ed902465e.png)**

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

```
npm install @formspree/react
```

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

たとえば、[Next.js](https://nextjs.org/) を使用している場合、トップレベルの `_app.js` ファイルは次のようになります：

```jsx
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 コマンドラインインターフェースをインストールし、プロジェクトを初期化します：

```shell
npm i -g @formspree/cli
formspree init
```

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

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

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

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

さまざまな設定オプションの詳細については、こちらの `formspree.json` リファレンスをご覧ください：[formspree.json ファイル](/articles/using-the-cli/the-formspree-json-file/)

### 環境変数

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

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

```javascript
        ...
        "apiKey": "$FORMSPREE_MAILCHIMP_APIKEY" 
        ...
```

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

## React でフォームを構築する

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

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

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

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

```jsx
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 ライブラリ](/articles/working-with-react/the-formspree-react-library/)に関する記事をご覧ください。

## フォームのデプロイ

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

```shell
formspree deploy -k <your-deploy-key>
```

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

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

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

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

```shell
echo "FORMSPREE_DEPLOY_KEY=" >> .env.example
```

### 継続的デプロイ

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

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

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

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