---
title: "@xid-kit/nuxt"
description: "Nuxt 3 module with H3/Nitro server middleware and auto-imported Vue composables for SSR and full-stack apps."
locale: "en"
---

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

# @xid-kit/nuxt

## Status

Package status is **Current package**. The Nuxt module, H3/Nitro server middleware, and auto-imported composables are implemented. A real IdP round-trip on production infrastructure is still pending manual verification.

## Module setup

Add `@xid-kit/nuxt` to the `modules` array. The module auto-imports all [@xid-kit/vue](/sdks/vue) composables and registers a client-only plugin that installs `XidPlugin`.

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

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

## Composables (auto-imported)

```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>
```

## Server middleware (JWT auth)

`createXidServerMiddleware` returns an H3 event handler that verifies the JWT networklessly and writes `event.context.xidAuth`. Place the file in `server/middleware/`. Nitro registers files in that directory as global 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'],
})
```

## Reading auth in server routes

```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 }
})
```

## Exported API

| Export | Kind | Purpose |
| --- | --- | --- |
| `createXidServerMiddleware` | function | H3 event handler factory: verifies JWT, writes event.context.xidAuth, protects routes |
| `getXidAuth` | function | Read AuthResult from event.context.xidAuth in server routes and handlers |
| `XID_AUTH_CONTEXT_KEY` | string constant | Context key used to store auth result ('xidAuth') |
| `XidServerMiddlewareOptions` | type | jwtKey, issuer, authorizedParties, cookieName, protectedRoutes, onUnauthenticated |

## Security notes

- `event.context.xidAuth` is server-side only and is never sent to the browser.
- The middleware strips any client-supplied auth tokens and re-injects only the verified result.
- Place the middleware file in `server/middleware/` to ensure it covers all routes as a global Nitro middleware.

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