clerk-nuxt-patterns

Nuxt のパターン

必要な情報は？

タスク	リファレンス
ミドルウェアでルートを保護する	references/nuxt-middleware.md
サーバー API ルート（Nitro）での認証	references/server-api-routes.md
コンポーネントでの useAuth / useUser	references/composables.md
SSR に対応した認証パターン	references/ssr-auth.md

リファレンス

リファレンス	説明
references/nuxt-middleware.md	ルート保護、clerkMiddleware()
references/server-api-routes.md	Nitro サーバールートの認証
references/composables.md	useAuth、useUser、useClerk
references/ssr-auth.md	SSR のハイドレーション、サーバーとクライアント

セットアップ

npm install @clerk/nuxt

.env：

NUXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_...
NUXT_CLERK_SECRET_KEY=sk_...

nuxt.config.ts：

export default defineNuxtConfig({
  modules: ['@clerk/nuxt'],
})

この1行で、ミドルウェア、プラグイン、コンポーネントの自動インポートが自動設定されます。

基本的な考え方

@clerk/nuxt はすべての Clerk コンポーネントとコンポーザブルを自動インポートするため、<script setup> で明示的にインポートする必要はありません。

• コンポーザブル（useAuth、useUser）— クライアント側でリアクティブに動作し、<script setup> 内で使用します
• サーバールート（clerkClient）— Nitro のサーバールートで使用し、event.context.auth を使います
• ミドルウェア（clerkMiddleware）— 自動登録されます。ルートを保護するには auth().protect() を使います

最小限のパターン

<script setup lang="ts">
definePageMeta({ middleware: 'auth' })
const { userId } = useAuth()
</script>

<template>
  <Show when="signed-in">
    <p>Hello {{ userId }}</p>
  </Show>
</template>

definePageMeta({ middleware: 'auth' }) は、@clerk/nuxt に組み込まれている認証ミドルウェアを使用します。

よくある問題

症状	原因	対処法
サーバー上でコンポーザブルが undefined を返す	useAuth はクライアント専用です	サーバールートでは event.context.auth を使います
ルートが保護されていない	middleware: 'auth' メタデータがありません	definePageMeta({ middleware: 'auth' }) を追加します
clerkClient が利用できない	インポートパスが正しくありません	@clerk/nuxt/server からインポートします
ハイドレーションの不一致	マウント前に認証状態をレンダリングしています	<ClientOnly> で囲むか、isLoaded を確認します
環境変数が読み込まれない	プレフィックスが正しくありません	Nuxt では、公開用に NUXT_PUBLIC_、サーバー用に NUXT_ が必要です

組織対応パターン

<script setup lang="ts">
const { orgId, orgRole } = useAuth()
</script>

<template>
  <div v-if="orgId">
    <p>Org: {{ orgId }}</p>
    <p v-if="orgRole === 'org:admin'">Admin panel</p>
  </div>
  <div v-else>
    <OrganizationSwitcher />
  </div>
</template>

関連項目

• clerk-setup - Clerk の初期インストール
• clerk-custom-ui - カスタムフローと外観
• clerk-orgs - B2B 組織

ドキュメント

Nuxt SDK