---
title: "@xid-kit/astro"
description: "정적 및 서버 렌더링 Astro 사이트를 위한 SSR 미들웨어, 서버 헬퍼, island 클라이언트 싱글턴을 갖춘 Astro 통합."
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/astro

## 상태

패키지 상태: **현재 패키지**. Astro 통합, SSR 미들웨어, 서버 헬퍼, island 클라이언트 싱글턴이 구현되었습니다. 프로덕션 인프라에서의 실제 IdP 왕복 테스트는 아직 수동 검증 대기 중입니다.

## 통합 설정

`astro.config.mjs`에 `xidIntegration`을 등록하세요. 통합은 `addMiddleware`를 통해 순서 `pre`에서 인증 미들웨어를 주입하고 클라이언트 island에 공개 키를 제공합니다.

```js
// astro.config.mjs
import { defineConfig } from 'astro/config'
import { xidIntegration } from '@xid-kit/astro'
import node from '@astrojs/node'

export default defineConfig({
  output: 'server',
  adapter: node({ mode: 'standalone' }),
  integrations: [
xidIntegration({
  publishableKey: import.meta.env.PUBLIC_XID_PK,
  jwtKey: import.meta.env.XID_JWT_KEY,
  protectedRoutes: ['/dashboard', '/account'],
  signInUrl: '/sign-in',
}),
  ],
})
```

## 수동 미들웨어(대안)

```ts
// src/middleware.ts
import { sequence } from 'astro:middleware'
import { createXidMiddleware } from '@xid-kit/astro'

export const onRequest = sequence(
  createXidMiddleware({
jwtKey: import.meta.env.XID_JWT_KEY,
issuer: 'https://xid.dev',
protectedRoutes: ['/dashboard', '/account'],
signInUrl: '/sign-in',
  }),
)
```

## .astro 페이지의 서버 측 인증

```astro
---
// src/pages/dashboard.astro
import { getAuth, currentUser } from '@xid-kit/astro/server'

const auth = getAuth(Astro.locals)
if (!auth.userId) return Astro.redirect('/sign-in')

const user = await currentUser(Astro.locals, {
  secretKey: import.meta.env.XID_SECRET_KEY,
})
---

<h1>Welcome, {user?.primaryEmailAddress}</h1>
```

## 클라이언트 island

```tsx
// src/components/SignOutButton.tsx
import { getClient } from '@xid-kit/astro/client'

export default function SignOutButton() {
  const client = getClient()

  const handleSignOut = async () => {
await client.signOut()
window.location.href = '/'
  }

  return <button onClick={handleSignOut}>Sign out</button>
}
```

## Astro.locals 타입 정의

`Astro.locals.xidAuth`에 대한 완전한 타입 커버리지를 얻으려면 `src/env.d.ts`에 타입 참조를 추가하세요.

```ts
/// <reference path="../node_modules/@xid-kit/astro/src/locals.d.ts" />
```

## 내보내진 API

| 내보내기 | 종류 | 모듈 |
| --- | --- | --- |
| `xidIntegration` | Astro 통합 팩토리 | `@xid-kit/astro` |
| `createXidMiddleware` | 미들웨어 팩토리 | `@xid-kit/astro` |
| `getAuth, currentUser, xidClient` | 서버 헬퍼 | `@xid-kit/astro/server` |
| `getClient, initClient, resetClient` | island 클라이언트 싱글턴 | `@xid-kit/astro/client` |

## 보안 참고 사항

- `jwtKey`는 JWKS 공개 키이므로 네트워크 호출 없는 검증에 안전하게 사용할 수 있으며 개인 키를 포함하지 않습니다.
- `secretKey`(`sk_live_xxx`)는 반드시 서버 측에서만 사용해야 합니다. island나 클라이언트 번들에 전달하지 마세요.
- 보호된 라우트는 페이지 핸들러가 실행되기 전에 미들웨어에서 `Response.redirect`를 통해 리디렉션됩니다. 클라이언트 측 JS가 필요하지 않습니다.
- 네트워크 호출 없는 JWT 검증 경로를 위해 [@xid-kit/backend](/ko/sdks/backend) `authenticateRequest`를 재내보냅니다.

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