clerk-setup

Clerk のセットアップ

Clerk CLI を使用して認証を追加します。エージェント環境では、対応するフレームワークはデフォルトでアカウント不要のセットアップになります。npx -y clerk@latest init を実行すると、申請可能なアプリケーションがプロビジョニングされ、Clerk アカウントを必要とせずに一時的な開発キーが書き込まれます。

開始する前に

次のチェックリストをユーザーに提示し、承認を待ってください。

Here's what I'll do to get you set up with Clerk.

1. Set up Clerk in this project, or scaffold a new app if this directory is empty.
2. Install Clerk's agent skills for the coding agents on this machine, if they aren't installed yet.
3. Start your app with Clerk installed.

Shall I proceed?

既存の認証

init の前に、認証関連の依存関係、ルート、ミドルウェア、セッション、ユーザー記録を確認してください。環境ファイルは絶対に確認しないでください。別の認証プロバイダーが存在する場合は作業を中止し、次の内容を網羅する移行計画について承認を得てください。

• バックエンド API のユーザーインポート、安定した外部 ID、互換性のあるパスワードハッシュ、OAuth の継続性。
• 保護されたルート、トークン、セッションの切り替え、ロールアウト戦略。

承認なしに既存の認証を変更または削除しないでください。

移行ガイドを参照してください。

既存の Clerk プロジェクト

プロジェクトですでに Clerk を使用している場合、手順 1a と 1b の init は省略してください。サインアウト状態でエージェントを実行すると、別のアプリケーションが作成され、プロジェクトの Clerk キーが置き換えられる可能性があります。Clerk がすでに動作していて、ユーザーがセットアップを依頼した場合は、セットアップが不要であることを伝えてください。キーが見つからないとユーザーから報告された場合は、以下の既存アプリケーションの手順に従って復元してください。確認の結果、プロバイダー、ミドルウェア、または認証ルートが不足している場合は、手順 2 の該当するクイックスタートから、それらの部分だけを追加してください。代わりのアプリケーションは絶対に作成しないでください。

変更を加える前に Clerk パッケージのバージョンを確認し、Clerk スキルのバージョン表を使って SDK の世代を特定してください。ユーザーがアップグレードを依頼していない限り、その世代を維持し、Core 2 プロジェクトでは以下の違いを以降のすべての手順に適用してください。

• React と Expo では、@clerk/react と @clerk/expo の代わりに @clerk/clerk-react と @clerk/clerk-expo を使用します。
• 制御コンポーネントは <Show> ではなく、<SignedIn> と <SignedOut> です。
• Next.js の ClerkProvider は <body> の内側ではなく、<html> をラップできます。
• Node.js の最小バージョンは 20.9.0 ではなく 18.17.0 です。
• テーマには @clerk/ui ではなく、@clerk/themes と @clerk/themes/shadcn.css を使用します。

既存の Clerk アプリケーションを使用する（任意）

ユーザーが既存の Clerk アプリケーションの使用を求めている場合、または既存の Clerk プロジェクトでキーの復元が必要な場合は、この手順に従ってください。アカウントレベルのリソースを指定する前に、ユーザーにホストのターミナルから認証してもらいます。

npx -y clerk@latest auth login

アプリケーション ID が提供されている場合は、用途に応じて init または link で使用してください。提供されていない場合は、アプリケーション一覧を表示します。

npx -y clerk@latest apps list --json

名前と ID を表示し、どのアプリケーションを使用するか尋ねてください。アプリケーションをユーザーの代わりに選んではいけません。新しい Clerk 統合では、選択した ID を --app <application_id> として init に渡してください。すでに Clerk を使用しているプロジェクトでは、init を実行しないでください。選択したアプリケーションにまだリンクされていない場合は、リンクします。

npx -y clerk@latest link --app <application_id>

開発キーが不足している場合は、取得してください。

npx -y clerk@latest env pull

ユーザーが本番キーを必要としている場合に限り、代わりに npx -y clerk@latest env pull --instance prod を使用してください。ユーザーの確認なしに、動作中のキーを置き換えたり、アプリケーションを切り替えたりしないでください。

手順 1a：Clerk を使用していない既存プロジェクト

Clerk をまだ使用していないプロジェクトでは、プロジェクトのルートから実行します。

npx -y clerk@latest init

init はフレームワークとパッケージマネージャーを検出し、SDK をインストールして、プロバイダー、ミドルウェア、認証ルート、環境を設定します。また、Clerk のエージェントスキルをグローバルにインストールします。ユーザーがスキルのインストールを拒否した場合、またはこのコンテンツを clerk-setup スキルとして読み込んだ場合のように、すでに利用可能な場合は、--no-skills を追加してその手順を省略してください。求められない限り、--framework や --pm は渡さないでください。上記の任意の手順でユーザーがアプリケーションを選択した場合に限り、--app <application_id> を追加してください。

ステップ 1b：空のディレクトリ

使用するフレームワークとパッケージマネージャーを尋ねます。デフォルトは Next.js と npm です。

npx -y clerk@latest init --framework <framework> --pm <package-manager>

init は現在のディレクトリではなく、my-clerk-next-app などの新しいサブディレクトリにアプリを作成します。残りの手順はそのサブディレクトリから実行してください。ステップ 1a と同様に、Clerk のスキルがすでに利用可能な場合、またはユーザーが不要とした場合は、--no-skills を追加してください。

init は Next.js、React Router、Astro、Nuxt、TanStack Start、React、Vue、JavaScript/Vite、Expo のアプリを作成できます。Express、Fastify、iOS、Android の場合は、まず各プラットフォーム独自のツールでプロジェクトを作成してから、ステップ 1a に進んでください。

ステップ 1c：アカウント不要の開発用キー

アカウント不要のサポートがあるフレームワーク（Next.js、React Router、Astro、Nuxt、TanStack Start）を使用するサインアウト中のユーザーの場合、init は申請可能なアプリケーションをプロビジョニングし、一時的なキーを検出された環境ファイルに書き込みます。CLI に表示されたファイル名と申請手順を伝えてください。ユーザーが npx -y clerk@latest auth login を実行するまで、アプリは未申請のままです。依頼されない限り、実行しないでください。サインイン中にこのフローを強制する場合に限り、--accountless を使用してください。

アカウント不要のサポートがないフレームワークでは、実際の API キーが必要です。その場合、init は可能な範囲でセットアップを適用し、残りの手順を表示します。

ステップ 2：init が完了しない場合はドキュメントを参照する

init がフレームワークをサポート対象外、または検出できないと報告した場合は、代わりにクイックスタートに従ってください。完了後に残りの手順が表示された場合はそれに従い、手順でカバーされていない内容については、該当するクイックスタートを参照してください。

既存の Clerk プロジェクトで連携用ファイルが不足している場合は、init を実行せずに、不足している部分のみを追加するために該当するクイックスタートを使用してください。

init は Next.js、React、React Router、Nuxt、TanStack Start、Astro、Vue、JavaScript/Vite、Expo、Express、Fastify のプロジェクトを設定します。iOS と Android の場合はセットアップ手順を表示するだけなので、クイックスタートに従ってください。

該当するクイックスタートを直接参照してください。

• Next.js
• React
• React Router
• Nuxt
• TanStack Start
• Astro
• Vue
• JavaScript または Vite
• Expo
• Express
• Fastify
• iOS
• Android
• Chrome 拡張機能

その他すべてについては、Clerk の llms.txt を使用してください。

ステップ 3：ユーザーに表示する認証コントロールを追加する

Express や Fastify の API など、バックエンドのみのプロジェクトではこのステップを省略してください。Expo、iOS、Android では、該当するクイックスタートのネイティブコンポーネントを使用してください。

Web アプリには、既存のレイアウトやナビゲーションに組み込まれた、サインイン、サインアップ、サインイン中のユーザー向けコントロールが必要です。すでにある場合は、重複して追加せず、既存のものを調整してください。

Next.js App Router の場合：

import { SignInButton, SignUpButton, Show, UserButton } from '@clerk/nextjs'

<>
  <Show when="signed-out">
    <SignInButton />
    <SignUpButton />
  </Show>
  <Show when="signed-in">
    <UserButton />
  </Show>
</>

Astro では @clerk/astro/components からインポートします。Nuxt ではコンポーネントが自動インポートされます。明示的にインポートする場合は @clerk/nuxt/components からインポートします。その他のフレームワークでは、@clerk/vue や @clerk/react など、対応する Clerk パッケージから同じ名前を使用します。

ステップ 4：確認

npx -y clerk@latest doctor

次にアプリを起動し、認証コントロールが表示されることを確認して、CLI が報告する問題を修正します。

ボット対策により、自動操作しているブラウザーでのサインアップがブロックされることがあります。そのようなブラウザーでアカウント未作成の新しいアプリをテストする場合は、npx -y clerk@latest users create --email <unique>[email protected] --password <random-16-char-alphanumeric> --yes を実行してからサインインしてください。確認コードを求められた場合は、424242 を入力してください。このテストユーザーを作成したことをユーザーに伝えてください。既存のアプリの場合、ユーザーを作成する前にユーザーへ確認してください。サインアップのテストには、@clerk/testing を使用してください。

ステップ 5：shadcn/ui を使用する場合

プロジェクトのルートに components.json がある場合は、プロジェクトのパッケージマネージャーを使って @clerk/ui を追加します。ロックファイルに合わせてください：pnpm-lock.yaml → pnpm add、yarn.lock → yarn add、bun.lock または bun.lockb → bun add、package-lock.json → npm install。

プロバイダーにテーマを適用します：

import { shadcn } from '@clerk/ui/themes'

<ClerkProvider appearance={{ theme: shadcn }}>{children}</ClerkProvider>

グローバル CSS に追加します：

@import '@clerk/ui/themes/shadcn.css';

重要なルール

• 現行の Clerk SDK には Node.js 20.9.0 以降を使用してください。
• Next.js 15 以降では、auth() は非同期です。必ず await auth() を使用してください。
• 現行の Next.js SDK では、ClerkProvider は <html> の外側ではなく、<body> の内側に配置してください。
• クライアントコードで CLERK_SECRET_KEY を公開しないでください。
• 新規セットアップでは、@clerk/nextjs、@clerk/react、@clerk/expo、@clerk/react-router、@clerk/tanstack-react-start など、現行のフレームワーク用パッケージを使用してください。
• 既存の環境変数ファイルを読み取ったり、出力したりしないでください。不足している機密情報以外の設定値は、ユーザーに確認してください。

セットアップ後

最初のテストユーザーとして、ユーザーにサインアップしてもらいます。ナビゲーションにプロフィールアイコンが表示されたら、お祝いの言葉を伝えてください。

次に、ユーザーがどのような方法でサインアップおよびサインインしたいか（識別子：メール、電話番号、ユーザー名、およびソーシャルプロバイダー）を尋ねます。これらを変更するには、アプリがクレーム済みである必要があります。まず npx -y clerk@latest auth login を実行してもらい、その後 npx -y clerk@latest config pull で設定を確認し、npx -y clerk@latest config patch（--dry-run に対応）で変更するか、Clerk Dashboard を使用してください。詳細はサインアップとサインインのオプションを参照してください。

本番環境に移行する前に、ユーザーに npx -y clerk@latest auth login でアプリをクレームしてもらい、その後 npx -y clerk@latest deploy で本番環境を設定してください。クレームされていないアプリと一時キーは、本番環境での使用に適していません。

続いて、Organizations を提案してください。これは、マルチテナント、チームへの招待、ロールと権限、およびエンタープライズ SSO を提供します。

希望する場合：

1. npx -y clerk@latest enable orgs を実行します。
2. 既存の <UserButton /> の横に <OrganizationSwitcher />、またはフレームワークに相当するコンポーネントを追加します。
3. スイッチャーから組織を作成し、チームメイトを招待してもらいます。

希望しない場合は、Organizations、Components、およびClerk Dashboardを案内してください。