---
title: "@xid-kit/nuxt"
description: "SSR 및 풀스택 앱을 위한 H3/Nitro 서버 미들웨어와 자동 가져오기 Vue composable이 있는 Nuxt 3 모듈."
locale: "ko"
---

> Documentation Index
> Fetch the locale documentation index at: https://xid.dev/ko/llms.txt
> Use this file to discover all available pages before exploring further.

# @xid-kit/nuxt

## 상태

패키지 상태: **현재 패키지**. Nuxt 모듈, H3/Nitro 서버 미들웨어, 자동 가져오기 composable이 구현되었습니다. 프로덕션 인프라에서의 실제 IdP 왕복 테스트는 아직 수동 검증 대기 중입니다.

## 모듈 설정

`modules` 배열에 `@xid-kit/nuxt`를 추가하세요. 이 모듈은 모든 [@xid-kit/vue](/ko/sdks/vue) composable을 자동으로 가져오고 `XidPlugin`을 설치하는 클라이언트 전용 플러그인을 등록합니다.

```ts
// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@xid-kit/nuxt'],

  runtimeConfig: {
public: {
  xidApiUrl: '', // optional: omit for same-origin deployment
},
  },
})
```

## Composables (자동 가져오기)

```vue
<script setup lang="ts">
// No import needed -- Nuxt auto-imports from @xid-kit/vue
const auth = useAuth()
const userRef = useUser()
const orgRef = useOrganization()
const sessionRef = useSession()
</script>

<template>
  <div v-if="auth.isSignedIn">
Signed in as {{ auth.userId }}
<button @click="auth.signOut()">Sign out</button>
  </div>
</template>
```

## 서버 미들웨어(JWT 인증)

`createXidServerMiddleware`는 JWT를 네트워크 호출 없이 검증하고 `event.context.xidAuth`에 결과를 기록하는 H3 이벤트 핸들러를 반환합니다. Nitro가 전역 미들웨어로 등록할 수 있도록 파일을 `server/middleware/`에 배치하세요.

```ts
// server/middleware/xid.ts
import { createXidServerMiddleware } from '@xid-kit/nuxt'

export default createXidServerMiddleware({
  jwtKey: JSON.parse(process.env.XID_JWKS_PUBLIC_KEY!),
  issuer: 'https://acme.xid.dev',
  protectedRoutes: ['/api/admin'],
})
```

## 서버 라우트에서 인증 읽기

```ts
// server/routes/api/me.get.ts
import { getXidAuth } from '@xid-kit/nuxt'

export default defineEventHandler((event) => {
  const auth = getXidAuth(event)
  if (!auth.userId) {
throw createError({ statusCode: 401, message: 'Unauthorized' })
  }
  return { userId: auth.userId, orgId: auth.orgId }
})
```

## 내보내진 API

| 내보내기 | 종류 | 목적 |
| --- | --- | --- |
| `createXidServerMiddleware` | function | H3 이벤트 핸들러 팩토리: JWT를 검증하고 event.context.xidAuth에 기록하며 라우트를 보호합니다 |
| `getXidAuth` | function | 서버 라우트와 핸들러의 event.context.xidAuth에서 AuthResult를 읽습니다 |
| `XID_AUTH_CONTEXT_KEY` | 문자열 상수 | 인증 결과를 저장하는 데 사용되는 컨텍스트 키('xidAuth') |
| `XidServerMiddlewareOptions` | type | jwtKey, issuer, authorizedParties, cookieName, protectedRoutes, onUnauthenticated |

## 보안 참고 사항

- `event.context.xidAuth`는 서버 전용이며 브라우저로 전송되지 않습니다.
- 미들웨어는 클라이언트가 제공한 인증 토큰을 제거하고 검증된 결과만 다시 주입합니다.
- 모든 라우트를 전역 Nitro 미들웨어로 커버할 수 있도록 미들웨어 파일을 `server/middleware/`에 배치하세요.

Source: https://xid.dev/ko/sdks/nuxt/index.mdx