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

> Documentation Index
> Fetch the relevant documentation index at: https://vonvon.id/ko/sdks/llms.txt
> Use this file to discover all available pages before exploring further.

# @vonvon-kit/nuxt

## 상태

Registry 상태: UNPUBLISHED. 이 SDK는 저장소 소스 checkout에서만 설치하고 외부 package registry를 사용하지 마세요.

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

## 모듈 설정

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

```ts
// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@vonvon-kit/nuxt'],
  vonvon: {
browser: {
  mode: 'oidc',
  issuer: 'https://vonvon.id',
  clientId: 'client_abc123',
  redirectUri: 'https://app.example.com/auth/callback',
},
  },
})
```

## Composables (자동 가져오기)

```vue
<script setup lang="ts">
// No import needed -- Nuxt auto-imports from @vonvon-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 인증)

`createVonvonServerMiddleware`는 Bearer 또는 명시적인 애플리케이션 JWT를 검증하고 `event.context.vonvonAuth`에 기록하는 H3 핸들러를 반환합니다. 동일 출처 Core 세션은 `sessionTokenExchange`로 설정하며 H3 v1 상대 URL에는 신뢰할 수 있는 `requestOrigin`도 필요합니다. Nitro가 전역 미들웨어로 등록하도록 파일을 `server/middleware/`에 배치하세요.

```ts
// server/middleware/vonvon.ts
import { createVonvonServerMiddleware } from '@vonvon-kit/nuxt'

export default createVonvonServerMiddleware({
  jwtKey: JSON.parse(process.env.VONVON_JWKS_PUBLIC_KEY!),
  issuer: 'https://acme.vonvon.id',
  sessionTokenExchange: { endpoint: '/v1/sessions/token' },
  requestOrigin: process.env.VONVON_APP_ORIGIN!,
  protectedRoutes: ['/api/admin'],
})
```

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

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

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

## 내보내진 API

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

## 보안 참고 사항

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

Source: https://vonvon.id/ko/sdks/nuxt/index.mdx