# Stripe Apps の使用を開始する

Stripe ダッシュボードでアプリを構築することで、アプリ開発の基礎を学習します。

Stripe ダッシュボードの顧客詳細ページに表示する*UI 拡張機能* (A set of APIs that allow you to inject user interface elements into the Stripe Dashboard using TypeScript and React)を備えた「Hello, world!」サンプルアプリを構築します。

## コーディングエージェントを使用する

Stripe Apps スキルを使用すると、コーディングエージェントで Stripe の最新ガイダンスに基づいて Stripe アプリの雛形を作成し、構築、プレビュー、テストできます。[Stripe のエージェントスキルをインストール](https://docs.stripe.com/skills.md)してから、アプリを作成するディレクトリで新しいエージェントセッションを開始し、次のプロンプトを使用します。

```bash
Use the Stripe Apps skill to build a "Hello, world!" Stripe app that displays a UI extension on the Customer details page. Guide me through previewing and testing it.
```

以下のステップバイステップガイドもご参照ください。

## はじめに

> **既存の Stripe 拡張機能がある場合のアプリ開発**
> 
> 既存の *Connect* (Connect is Stripe's solution for multi-party businesses, such as marketplace or software platforms, to route payments between sellers, customers, and other recipients) 拡張機能をお持ちの場合は、[Stripe Apps への移行](https://docs.stripe.com/stripe-apps/migrate-connect-extension.md)を参照してください。

1. [Stripe ダッシュボードにサインイン](https://dashboard.stripe.com)するか、[アカウントを作成](https://dashboard.stripe.com/register/stripe_apps)します。
2. [Stripe CLI をインストール](https://docs.stripe.com/cli/install)します。すでにインストールされている場合は、以下を実行して、バージョン 1.52.0 以降を使用していることを確認してください。
   ```bash
   stripe version
   ```
バージョンが 1.52.0 より前の場合は、[Stripe CLI をアップグレード](https://docs.stripe.com/cli/upgrade)します。
3. 以下を実行して、Stripe CLI にログインします。
   ```bash
   stripe login
   ```
指示に従って、ダッシュボードで使用しているのと同じ Stripe アカウントを選択します。
4. 次のコマンドを実行して、[Node.js](https://nodejs.org/) がインストールされていることを確認します:
   ```bash
   node -v
   ```
Stripe Apps には、Node.js バージョン `>=22` が必要です。[アクティブ LTS バージョン](https://nodejs.org/en/about/previous-releases) (22 以降) の使用をお勧めします。Node.js がインストールされていない場合は、[ダウンロードしてインストール](https://nodejs.org/en/download/)してください。
5. [pnpm](https://pnpm.io/installation) をインストールします。Stripe Apps では、パッケージマネージャーとして pnpm を使用します。
   ```bash
   brew install pnpm
   ```
インストールを確認します。
   ```bash
   pnpm --version
   ```

アプリを [App Marketplace に公開する](https://docs.stripe.com/stripe-apps/publish-app.md)予定がある場合は、追加の制限事項があります。

- メールアドレスと事業情報の確認が済んでいる[本番環境の Stripe アカウント](https://docs.stripe.com/get-started/account/set-up.md)が必要です。
- [Connect プラットフォームアカウント](https://docs.stripe.com/connect.md)では、Stripe App Marketplace にアプリを公開できません。

[拡張機能](https://docs.stripe.com/extensions/how-extensions-work.md)を作成する場合は、以下を用意します。

| 前提条件 | セットアップ |
| --- | --- |
| 拡張機能のプライベートプレビューへのアクセス権限がある [Stripe アカウント](https://docs.stripe.com/get-started/account/set-up.md) | アクセス権がない場合は、先行提供版に[登録](https://docs.stripe.com/stripe-apps/create-app.md#signup)してください。 |
| アカウントにログイン済みの [Stripe CLI](https://docs.stripe.com/cli.md) v1.52.0 以降 | `stripe version` を実行して確認します。必要に応じて[インストール](https://docs.stripe.com/cli/install)または[アップグレード](https://docs.stripe.com/cli/upgrade)します。 |
| [サンドボックス](https://docs.stripe.com/sandboxes.md) (初回のセットアップで推奨) | サンドボックスがない場合は、ダッシュボードで作成します。 |
| [Node.js](https://nodejs.org) v22 以降 | `node --version` |
| [pnpm](https://github.com/pnpm/pnpm/releases) v10 (v11 はサポートされていません) | `pnpm --version` |
| [Stripe Apps CLI プラグイン](https://docs.stripe.com/stripe-apps/create-app.md#install-stripe-apps-cli) v1.19.0 以降 | `stripe plugin install apps` を実行してインストールし、`stripe apps -v` で確認します |
| generate プラグイン v0.11.5 以降 | `stripe generate --version` で確認 |

## Stripe Apps CLI プラグインをインストールする

Stripe アプリの構築を開始するために、Stripe Apps CLI プラグインをインストールします。

```bash
stripe plugin install apps
```

`apps` プラグインがすでにインストールされている場合は、バージョンが `1.19.0` 以降であることを確認してください。

```bash
stripe apps -v
# apps version 1.19.0
```

`apps` プラグインがインストール済みの場合は、以下を実行して最新バージョンにアップグレードすることをお勧めします。

```bash
stripe plugin upgrade apps
```

## Generate CLI プラグインのバージョンを確認する

Generate プラグインでコード生成コマンドを Stripe CLI に追加します。`stripe generate app` を使用して、アプリの初期プロジェクトと設定を作成します。Apps プラグインには、アプリの開発、プレビュー、アップロードを行うためのコマンドが用意されています。

Generate プラグインは、`stripe generate` コマンドを初めて実行したときに自動的にインストールされます。バージョンが `0.11.5` 以降であることを確認してください。

```bash
stripe generate --version
# generate version 0.11.5
```

`generate` プラグインがインストール済みの場合は、以下を実行して最新バージョンにアップグレードすることをお勧めします。

```bash
stripe plugin upgrade generate
```

## アプリを作成する

1. 「Hello, world!」アプリの基本構造を構築します。

   ```bash
   stripe generate app helloworld
   cd helloworld
   ```

2. 指示に従い、以下の情報を入力します。

   - **ID**: 自動生成されたアプリ ID を受け入れるか、カスタマイズします。Stripe は、これによってアプリを識別します。[アプリ ID](https://docs.stripe.com/stripe-apps/reference/app-manifest.md#schema) はグローバルに一意である必要があります。
   - **表示名**: 表示名を入力します。これは、ダッシュボードに表示されるアプリの名前です。この名前は後でいつでも変更できます。

### アプリディレクトリのファイル構造

| ファイルパス | 説明 |
| --- | --- |
| `src/views/` | Stripe ダッシュボードで UI 要素を作成する TypeScript ファイルのためのディレクトリ。*ビュー* (A view is a React component that creates UI extensions in the Stripe Dashboard) とも呼ばれます。 |
| `src/views/App.tsx` | Customer details ページが Stripe ダッシュボードでレンダリングするサンプル *ビュー* (A view is a React component that creates UI extensions in the Stripe Dashboard)。 |
| `src/views/App.test.tsx` | `App.tsx` ビューの機能のテストファイル。 |
| `stripe-app.json` | アプリが Stripe プラットフォームとどのように統合されるかを説明する *アプリマニフェスト* (In a Stripe App, the app manifest is a stripe-app.json file in your app's root directory. It defines your app's ID, views, permissions, and other essential properties) ファイル。 |
| `package.json` | アプリの依存関係を処理するためのメタデータが含まれるファイル。 |
| `yarn.lock` | アプリの依存関係の現在のバージョンをリストする、自動生成されたファイル。 |
| `jest.config.ts` | テストファイルを実行するための構成ファイル。 |
| `images.d.ts` | Stripe アプリで画像ファイルをサポートするための型宣言。 |
| `tsconfig.json` | TypeScript ファイルをコンパイルするための構成ファイル。 |
| `.eslintrc.json` | TypeScript ファイルをリンティングするための構成ファイル。 |
| `.vscode/extensions.json` | 推奨される VS Code 拡張機能を含むファイル。 |
| `.gitignore` | git に特定のファイルまたはフォルダーを無視するように伝えるファイル。 |

Stripe Apps は React 17 のみをサポートしています。インストールするすべての依存関係が、このバージョンと互換性があることを確認してください。詳細については、[UI拡張機能の仕組み](https://docs.stripe.com/stripe-apps/how-ui-extensions-work.md#apps-cant-control-the-react-version)をご覧ください。

## アプリをプレビューする

アプリをローカルで実行し、更新し、変更内容をダッシュボードでプレビューできます。

1. `helloworld` ディレクトリーに移動します。

   ```bash
   cd helloworld
   ```

2. アプリをプレビューするには、ローカルの開発サーバーを起動します。

   ```bash
   stripe apps start
   ```

3. **Enter** を押してブラウザーを開きます。

   > [Stripe ダッシュボードに対応しているブラウザー](https://docs.stripe.com/dashboard/basics.md)をご使用ください。Safari はダッシュボードに対応していません。その他の更新内容については、[GitHub 課題管理ブラウザーのサポート](https://github.com/stripe/stripe-apps/issues/146)でご確認ください。

4. **続行**をクリックして、Stripe アカウントでアプリをプレビューします。
![プレビューモードを有効にするスクリーンショット](https://b.stripecdn.com/docs-statics-srv/assets/enable_app_preview.7d71712d107d581e0a25a4ebaf71484e.png)
   
   アプリのプレビューを有効化
![Hello World アプリ](https://b.stripecdn.com/docs-statics-srv/assets/helloworld_app.7b1588ce22f93f72ab2ecd07c44dd041.png)
   
   ダッシュボードでのアプリ

アプリをプレビューする前に[ローカルネットワークアクセスを有効](https://docs.stripe.com/stripe-apps/enable-local-network-access.md)にしてください。

## アプリを構築する

ダッシュボードでアプリをプレビューしている間、ローカルの開発サーバーはアプリのリアルタイムの更新を有効にします。

1. Stripe ダッシュボードページを開き、開発サーバーを実行したまま、`Home.tsx` ファイルのタイトルを変更します。ファイルを保存して、アプリで変更内容を確認します。

2. 同じファイルで `</ContextView>` 終了タグから `>` を削除し、ファイルを保存してエラーを確認します。
![Hello World エラー](https://b.stripecdn.com/docs-statics-srv/assets/helloworld_error.ee7aeea9d33b54f1e17b108f61741e97.png)
   
   Stripe ダッシュボード、ブラウザーの開発者ツール、Stripe CLI のエラーを解決できます。

3. 開発サーバーを停止するには、コマンドラインから **Ctrl+C** を使用します。

これで、サンプルアプリは完成です。次に、Stripe アプリに機能を追加してください。

## See also

- [UI 拡張機能を構築する](https://docs.stripe.com/stripe-apps/build-ui.md)
- [サーバー側のロジックを追加する](https://docs.stripe.com/stripe-apps/build-backend.md)
- [配布オプション](https://docs.stripe.com/stripe-apps/distribution-options.md)

### 新しいアプリのコンポーネントと機能のベータ版に関心をお持ちの場合

Enter your email to request access.

```bash
curl https://docs.stripe.com/preview/register \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Referer: https://docs.stripe.com/stripe-apps/create-app" \
  -d '{"email": "EMAIL", "preview": "stripe_apps_private_preview"}'
```