workos-authkit-nextjs

Next.js 向け WorkOS AuthKit

ステップ 1：SDK ドキュメントの取得（必須）

停止してください。完了するまで先に進まないでください。

WebFetch：https://github.com/workos/authkit-nextjs/blob/main/README.md

README が唯一の正しい情報源です。このスキルの内容と README が矛盾する場合は、README に従ってください。

ステップ 2：事前検証

プロジェクト構成

• next.config.js または next.config.mjs が存在することを確認します
• package.json に "next" の依存関係が含まれていることを確認します

環境変数

.env.local で以下を確認します。

• WORKOS_API_KEY - sk_ で始まる
• WORKOS_CLIENT_ID - client_ で始まる
• NEXT_PUBLIC_WORKOS_REDIRECT_URI - 有効なコールバック URL
• WORKOS_COOKIE_PASSWORD - 32 文字以上

ステップ 3：SDK のインストール

パッケージマネージャーを検出し、README に記載された SDK パッケージをインストールします。

確認： 続行する前に、SDK パッケージが node_modules に存在することを確認します。

ステップ 4：バージョンの検出（判断ツリー）

package.json から Next.js のバージョンを読み取ります。

Next.js version?
  |
  +-- 16+ --> Create proxy.ts at project root
  |
  +-- 15   --> Create middleware.ts (cookies() is async - handlers must await)
  |
  +-- 13-14 --> Create middleware.ts (cookies() is sync)

重要： ファイルは必ずプロジェクトのルート（または src ディレクトリを使用している場合は src/）に置いてください。app/ 内には置かないでください。

Next.js 15 以降の非同期処理に関する注意： Cookie にアクセスするすべてのルートハンドラーとミドルウェアは、非同期にし、Cookie 操作を適切に await する必要があります。これは Next.js 14 からの破壊的変更です。

ミドルウェア／プロキシのコードについては、authkitMiddleware() のエクスポートパターンを README で確認してください。

既存のミドルウェア（重要）

middleware.ts にレート制限、ロギング、ヘッダーなどのカスタムロジックがすでにある場合は、authkitMiddleware ではなく authkit() コンポーザブル関数を使用してください。

既存のミドルウェアと組み合わせるパターン：

import { NextRequest, NextResponse } from 'next/server';
import { authkit, handleAuthkitHeaders } from '@workos-inc/authkit-nextjs';

export default async function middleware(request: NextRequest) {
  // 1. Get auth session and headers from AuthKit
  const { session, headers, authorizationUrl } = await authkit(request);
  const { pathname } = request.nextUrl;

  // 2. === YOUR EXISTING MIDDLEWARE LOGIC ===
  // Rate limiting, logging, custom headers, etc.
  const rateLimitResult = checkRateLimit(request);
  if (!rateLimitResult.allowed) {
    return new NextResponse('Too Many Requests', { status: 429 });
  }

  // 3. Protect routes - redirect to auth if needed
  if (pathname.startsWith('/dashboard') && !session.user && authorizationUrl) {
    return handleAuthkitHeaders(request, headers, {
      redirect: authorizationUrl,
    });
  }

  // 4. Continue with AuthKit headers properly handled
  return handleAuthkitHeaders(request, headers);
}

主な関数：

• authkit(request) - 組み合わせに使用する { session, headers, authorizationUrl } を返します
• handleAuthkitHeaders(request, headers, options?) - AuthKit ヘッダーが正しく引き継がれるようにします
• リライトには、partitionAuthkitHeaders() と applyResponseHeaders() を使用してください（README を参照）

重要： ページで withAuth() が機能するよう、必ず handleAuthkitHeaders() を介して返してください。

ステップ 5：コールバックルートの作成

NEXT_PUBLIC_WORKOS_REDIRECT_URI を解析して、ルートパスを決定します。

URI path          --> Route location
/auth/callback    --> app/auth/callback/route.ts
/callback         --> app/callback/route.ts

SDK の handleAuth() を使用してください。独自の OAuth ロジックは作成しないでください。

Next.js 15 以降では重要： ルートハンドラーは必ず非同期にし、handleAuth() を適切に await する必要があります。

// CORRECT - Next.js 15+ requires async route handlers
export const GET = handleAuth();

// If handleAuth returns a function, ensure it's awaited in request context

正確な使用方法は README で確認してください。ビルド時に「cookies outside request scope」というエラーが発生する場合、ハンドラーに async/await が不足している可能性があります。

ステップ 6：プロバイダーの設定（必須）

重要： 必ず app/layout.tsx でアプリを AuthKitProvider でラップしてください。

これは以下のために必要です。

• useAuth() フックによるクライアント側の認証状態
• クライアント／サーバーの境界を越えて一貫した認証 UX を実現する
• クライアント側認証を使用する Auth0 から適切に移行する

// app/layout.tsx
import { AuthKitProvider } from '@workos-inc/authkit-nextjs';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <AuthKitProvider>{children}</AuthKitProvider>
      </body>
    </html>
  );
}

正確なインポートパスを README で確認してください。@workos-inc/authkit-nextjs/components のようなサブパスのエクスポートである可能性があります。

他の場所でサーバー側の認証パターンを使用していても、このステップを省略しないでください。

ステップ 7：UI の統合

SDK 関数を使用して、app/page.tsx に認証 UI を追加します。getUser、getSignInUrl、signOut の使用方法は README を参照してください。

検証チェックリスト（すべて合格する必要があります）

統合を確認するため、以下のコマンドを実行してください。すべて合格するまで完了としないでください。

# 1. Check middleware/proxy exists (one should match)
ls proxy.ts middleware.ts src/proxy.ts src/middleware.ts 2>/dev/null

# 2. CRITICAL: Check AuthKitProvider is in layout (REQUIRED)
grep "AuthKitProvider" app/layout.tsx || echo "FAIL: AuthKitProvider missing from layout"

# 3. Check callback route exists
find app -name "route.ts" -path "*/callback/*"

# 4. Build succeeds
npm run build

チェック #2 が失敗した場合： ステップ 6 に戻り、AuthKitProvider を追加してください。これは省略できません。

エラーからの復旧

「cookies was called outside a request scope」（Next.js 15 以降）

最も一般的な原因： ルートハンドラーが適切に非同期化されていない、または await が不足しています。

コールバックルートの修正方法：

1. handleAuth() が直接エクスポートされていることを確認します：export const GET = handleAuth();
2. カスタムラッパーを使用している場合は、async にし、Cookie 操作をすべて await していることを確認します
3. authkit-nextjs SDK のバージョンが Next.js 15 以降に対応していることを確認します（互換性は README を参照）
4. 絶対に モジュールレベルで cookies() を呼び出さないでください。リクエストハンドラー内でのみ呼び出してください

このエラーにより OAuth コードが期限切れ（「invalid_grant」）になるため、まずハンドラーを修正してください。

「middleware.ts が見つかりません」

• 確認：プロジェクトのルートまたは src/ にファイルがあり、app/ の中には置かれていないこと
• 確認：ファイル名が Next.js のバージョンに合っていること（16 以降は proxy.ts、13～15 は middleware.ts）

「クライアントコンポーネントでは getUser を使用できません」

• 確認：コンポーネントに 'use client' ディレクティブがないこと、または
• 確認：認証ロジックをサーバーコンポーネント／API ルートに移すこと

SDK のインポートで「モジュールが見つかりません」

• 確認：インポートを記述する前に SDK がインストールされていること
• 確認：SDK のパッケージディレクトリが node_modules に存在すること

「withAuth ルートがミドルウェアでカバーされていません」

• 確認：ミドルウェア／プロキシファイルが正しい場所にあること
• 確認：Matcher 設定にルートパスが含まれていること

AuthKitProvider の後にビルドが失敗する

• 確認：正しいインポートパスが README に記載されていること（サブパスのエクスポートの場合があります）
• 確認：クライアント／サーバー境界の違反がないこと

NEXTPUBLIC プレフィックスに関する問題

• クライアントコンポーネントでは NEXT_PUBLIC_* プレフィックスが必要です
• サーバーコンポーネントではプレフィックスなしの環境変数名を使用します