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 プロジェクト

ネイティブの iOS または macOS アプリの場合は、代わりにiOS セットアッププロンプトに従ってください。リンク済みのアプリケーションを再利用し、既存の設定を維持できます。

プロジェクトですでに 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 を使用します。ユーザーの確認なしに、動作しているキーを置き換えたり、アプリケーションを切り替えたりしないでください。

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

Xcode でネイティブの iOS または macOS アプリを作成する場合は、以降の手順ではなく、iOS セットアッププロンプトに従ってください。

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

npx -y clerk@latest init

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

Step 1b：空のディレクトリ

ネイティブの iOS または macOS アプリを作成する場合は、以降の手順ではなく、iOS セットアッププロンプトに従ってください。Xcode プロジェクトの作成方法が記載されています。

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

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

init は、現在のディレクトリではなく、my-clerk-next-app のような新しいサブディレクトリにアプリを作成します。以降の手順はそのサブディレクトリから実行します。Step 1a と同様に、Clerk のスキルがすでに利用できる場合、またはユーザーがインストールを拒否した場合は、--no-skills を追加します。

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

Step 1c：アカウント不要の開発キー

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

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

Step 2: init が不完全な場合はドキュメントを参照する

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

既存の Clerk プロジェクトで統合ファイルが不足している場合は、init を実行せず、そのクイックスタートを使って不足している部分だけを追加してください。

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

対応する直接のクイックスタートを使用してください。

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

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

Step 3: 目に見える認証コントロールを追加する

Express や Fastify の API など、バックエンドのみのプロジェクトではこの手順を省略してください。Expo、iOS、Android では、代わりに対応するクイックスタートに記載されているネイティブコンポーネントを使用してください。

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

Next.js App Router で、<Show> が Server Component 内でレンダリングされる場合はリクエストを読み取るため、<Suspense> で囲んでください。

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

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

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

Step 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 を使用してください。

Step 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 で next.config に cacheComponents: true（create-next-app のデフォルト）が設定されている場合、<Suspense> の外でリクエストデータを読み取ると next build が失敗します。サーバーコンポーネントでレンダリングされる <Show> と、auth() または currentUser() を呼び出すサーバーコンポーネントは、認証に依存する UI にできるだけ近い場所で <Suspense> で囲んでください。キャッチオールルートの <SignIn />、<SignUp />、<UserProfile />、<OrganizationProfile /> ページも、Clerk CLI が作成するサインインページとサインアップページを含め、<Suspense> で囲んでください。Suspense 内で認証データを読み取るとキャッチオールルートでのビルトインコンポーネントを参照してください。
• 現在の 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を案内してください。