К основному содержанию
скилл CX Codex

next · vercel-labs/emulate — скилл для Claude Code: что делает и установка

Скилл для Claude Code подключает эмуляторы к Next.js App Router через @emulators/adapter-next. Настраивает OAuth, тестовые данные и сохранение состояния.

Apache-2.0 204 установок ★ 2 075 обновлён 2026-10-25

Установить в Claude Code · Через Skills CLI (Vercel) Все способы и платформы ↓
npx skills add vercel-labs/emulate --skill next -a claude-code
Открыть на GitHub

Что делает next

Скилл помогает встроить эмуляторы GitHub и Google прямо в Next.js App Router. Он создаёт catch-all route handler через createEmulateHandler, распределяет запросы по сервисам и позволяет задать seed-данные. Пути вроде /emulate/github/** работают на том же origin, что и приложение, что удобно для OAuth в Vercel preview.

Для Auth.js или NextAuth он настраивает OAuth URL эмулятора: authorization, token и userinfo. Конфигурацию Next.js можно обернуть в withEmulate, чтобы добавить шрифты эмулятора в serverless trace. Состояние по умолчанию хранится в памяти; для сохранения между cold start нужен адаптер persistence, например файл или хранилище вроде Vercel KV.

Сервер должен работать в Node.js runtime. В Edge этот скилл не запустится, потому что эмуляторы используют crypto.randomBytes; при параллельных изменениях действует last-write-wins.

Какие задачи решает

  • встроить GitHub и Google эмуляторы в Next.js
  • создать catch-all route handler для /emulate
  • настроить same-origin OAuth для Vercel preview
  • добавить seed-данные для тестовых пользователей
  • сохранить состояние эмуляторов между cold start

Примеры запросов агенту

  • Встрой GitHub и Google эмуляторы в Next.js App Router через createEmulateHandler и добавь seed-данные.
  • Настрой Auth.js так, чтобы OAuth использовал same-origin пути /emulate/github.
  • Добавь persistence для состояния эмулятора и оберни конфигурацию в withEmulate.

Как установить next

1Через Skills CLI (Vercel)

npx skills add vercel-labs/emulate --skill next -a claude-code

2Вручную: положить файлы

~/.claude/skills/next/SKILL.md

Папка скилла целиком; для одного проекта — .claude/skills/next/

По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов

Вопросы о next

Как установить next в Claude Code?

Выполни npx skills add vercel-labs/emulate --skill next -a claude-code. Скилл появится в ~/.claude/skills/next/SKILL.md.

Что делает скилл next?

Он встраивает эмуляторы в Next.js App Router, создаёт обработчик маршрутов, помогает настроить OAuth и поддерживает сохранение состояния через persistence-адаптер.

Запустится ли next в Edge runtime?

Нет. Эмуляторы требуют Node.js runtime, поскольку используют crypto.randomBytes. При параллельных изменениях сохранение работает по схеме last-write-wins.

Исходный текст

SKILL.md · Apache-2.0
---
name: next
description: Next.js adapter for embedding emulators directly in a Next.js app via @emulators/adapter-next. Use when the user needs to embed emulators in Next.js, set up same-origin OAuth for Vercel preview deployments, create an emulate catch-all route handler, configure Auth.js/NextAuth with embedded emulators, add persistence to embedded emulators, or wrap next.config with withEmulate. Triggers include "Next.js emulator", "adapter-next", "embedded emulator", "same-origin OAuth", "Vercel preview", "createEmulateHandler", "withEmulate", or any task requiring emulators inside a Next.js app.
allowed-tools: Bash(npx emulate:*)
---

# Next.js Integration

The `@emulators/adapter-next` package embeds emulators directly into a Next.js App Router app, running them on the same origin. This is particularly useful for Vercel preview deployments where OAuth callback URLs change with every deployment.

## Install

```bash
npm install @emulators/adapter-next @emulators/github @emulators/google
```

Only install the emulators you need. Each `@emulators/*` package is published independently, keeping serverless bundles small.

## Route Handler

Create a catch-all route that serves emulator traffic:

```typescript
// app/emulate/[...path]/route.ts
import { createEmulateHandler } from '@emulators/adapter-next'
import * as github from '@emulators/github'
import * as google from '@emulators/google'

export const { GET, POST, PUT, PATCH, DELETE, OPTIONS } = createEmulateHandler({
  services: {
    github: {
      emulator: github,
      seed: {
        users: [{ login: 'octocat', name: 'The Octocat' }],
        repos: [{ owner: 'octocat', name: 'hello-world', auto_init: true }],
      },
    },
    google: {
      emulator: google,
      seed: {
        users: [{ email: '[email protected]', name: 'Test User' }],
      },
    },
  },
})
```

This creates the following routes:

- `/emulate/github/**` serves the GitHub emulator
- `/emulate/google/**` serves the Google emulator

GitHub installation-token metadata is available server-side at `/emulate/github/_emulate/installation-tokens`.

## Auth.js / NextAuth Configuration

Point your provider at the emulator paths on the same origin:

```typescript
import GitHub from 'next-auth/providers/github'

const baseUrl = process.env.VERCEL_URL
  ? `https://${process.env.VERCEL_URL}`
  : 'http://localhost:3000'

GitHub({
  clientId: 'any-value',
  clientSecret: 'any-value',
  authorization: { url: `${baseUrl}/emulate/github/login/oauth/authorize` },
  token: { url: `${baseUrl}/emulate/github/login/oauth/access_token` },
  userinfo: { url: `${baseUrl}/emulate/github/user` },
})
```

No `oauth_apps` need to be seeded. When none are configured, the emulator skips `client_id`, `client_secret`, and `redirect_uri` validation.

## Font Tracing for Serverless

Emulator UI pages use bundled fonts. Wrap your Next.js config to include them in the serverless trace:

```typescript
// next.config.mjs
import { withEmulate } from '@emulators/adapter-next'

export default withEmulate({
  // your normal Next.js config
})
```

If you mount the catch-all at a custom path, pass the matching prefix:

```typescript
export default withEmulate(nextConfig, { routePrefix: '/api/emulate' })
```

## Persistence

By default, emulator state is in-memory and resets on every cold start. To persist state across restarts, pass a `persistence` adapter.

### Custom Adapter (Vercel KV, Redis, etc.)

```typescript
import { createEmulateHandler } from '@emulators/adapter-next'
import * as github from '@emulators/github'

const kvAdapter = {
  async load() { return await kv.get('emulate-state') },
  async save(data: string) { await kv.set('emulate-state', data) },
}

export const { GET, POST, PUT, PATCH, DELETE, OPTIONS } = createEmulateHandler({
  services: { github: { emulator: github } },
  persistence: kvAdapter,
})
```

### File Persistence (Local Dev)

For local development, `@emulators/core` ships a file-based adapter:

```typescript
import { filePersistence } from '@emulators/core'

// persists to a JSON file
persistence: filePersistence('.emulate/state.json'),
```

GitHub App seeds may omit `private_key`. Retain the handler and call server-only `generatedSecrets()`; explicit keys are excluded. Keep persisted snapshots private and implement `initialize` atomically.

### How Persistence Works

- **Cold start**: The adapter loads state from the persistence adapter. If found, it restores the full Store and token map (skipping seed). If not found, it seeds from config and saves the initial state.
- **After mutating requests** (POST, PUT, PATCH, DELETE): State is saved. Saves are serialized via an internal queue to prevent race conditions.
- **No persistence configured**: Falls back to pure in-memory. Seed data re-initializes on every cold start.

## How It Works

1. **Incoming request**: `/emulate/github/login/oauth/authorize?client_id=...`
2. **Parse**: service = `github`, rest = `/login/oauth/authorize`
3. **Strip prefix**: A new `Request` is created with the stripped path and forwarded to the GitHub service app
4. **Rewrite response**: HTML `action` and `href` attributes, CSS `url()` font references, and `Location` headers get the service prefix prepended
5. **Persist**: After mutating requests, state is saved via the persistence adapter

## Limitations

- Requires the Node.js runtime (not Edge) since emulators use `crypto.randomBytes`
- Concurrent mutations use last-write-wins semantics. Generated identities require `initialize` to select the initial snapshot atomically across cold starts.

## Config Reference

### `createEmulateHandler(config)`

| Field | Type | Description |
|-------|------|-------------|
| `services` | `Record<string, EmulatorEntry>` | Map of service name to emulator config |
| `persistence?` | `PersistenceAdapter` | Optional persistence adapter for state across cold starts |

Each `EmulatorEntry`:

| Field | Type | Description |
|-------|------|-------------|
| `emulator` | `EmulatorModule` | The emulator package (e.g. `import * as github from '@emulators/github'`) |
| `seed?` | `Record<string, unknown>` | Seed data matching the service's config schema |

### `withEmulate(nextConfig, options?)`

Wraps a Next.js config to include emulator font files in the serverless output trace. Call it around your exported config in `next.config.mjs` or `next.config.ts`.

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `routePrefix` | `string` | `"/emulate"` | The path prefix where the catch-all route is mounted |

### `PersistenceAdapter`

```typescript
interface PersistenceAdapter {
  load(): Promise<string | null>
  save(data: string): Promise<void>
  initialize?(data: string): Promise<string>
}
```

`initialize` must atomically create the initial value or return the value another instance created first. Implement it with compare-and-set semantics such as Redis `SET NX`. The built-in `filePersistence(path)` from `@emulators/core` provides this behavior for local development.

## Custom emulators

The adapter accepts definitions created with `defineEmulator` from `emulate` in `services[name].emulator`. Reuse the definition from CLI/tests; custom inspector is opt-in. Root-relative redirect locations stay under the service mount, while custom HTML bodies pass through unchanged. Await the returned handler's `close()` in test teardown. Install `emulate` as a runtime dependency for deployed definitions. See https://emulate.dev/docs/custom-emulators for seeds, snapshots, persistence, and lifecycle rules.

© vercel-labs · Apache-2.0 · vercel-labs/emulate

Похожие скиллы

Все скиллы по теме «Бэкенд и API» →

Сначала — next от других авторов.

next vercel-labs Превращает JSON-спецификации в приложения Next.js с маршрутами, страницами и серверным рендерингом. Включается при работе с @json-render/next и генерации многостраничных приложений из JSON. CX Codex +1 8 600установок next mag123c Скилл next для старта сессии: читает последний файл планирования, смотрит git-лог и говорит, что делать дальше. CX Codex +1 ★ 196звёзд репо authjs-skills gocallum Скилл authjs-skills для ИИ-агентов, который помогает подключить аутентификацию Auth.js v5 в Next.js: Google OAuth, вход по email и паролю, переменные окружения. CX Codex +1 798установок next-forge официальный Vercel Labs Скилл для Codex и ChatGPT с экспертными знаниями о next-forge — Turborepo-монорепо для SaaS-приложений на Next.js от Vercel. CX Codex GP ChatGPT +1 14установок next-cache-components официальный Vercel Labs Скилл next-cache-components для Codex помогает настраивать Cache Components в Next.js 16+. Он включается при работе с PPR, кэшированием и переходе с unstable_cache. CX Codex GP ChatGPT +1 4установок nextjs-authentication giuseppe-trisciuoglio Скилл nextjs-authentication даёт готовые шаблоны аутентификации для Next.js 15+ App Router на Auth.js 5: провайдеры, защита маршрутов, сессии и роли. CX Codex +1 4 000установок nextauth-authentication Mindrally Скилл nextauth-authentication учит агента внедрять аутентификацию через NextAuth.js (Auth.js v5) в Next.js. Помогает настроить сессии, роуты и защиту страниц. CX Codex +1 1 200установок oauth vercel-labs Скилл настраивает OAuth-провайдеров для работы с локальными доменами portless и убирает ошибки redirect_uri_mismatch. CX Codex +1 3 100установок

Из того же набора12

Весь набор →
resend Скилл запускает локальный Resend API, который принимает письма, сохраняет их в памяти и отдаёт через REST или UI. Реальные письма не отправляются. CX Codex +1 246установок aws Скилл aws для Claude Code поднимает локальную эмуляцию сервисов AWS для отладки приложений без обращения к реальному облаку. CX Codex +1 241установок github Запускает локальную эмуляцию GitHub REST API с сохранением состояния. Помогает тестировать вебхуки, OAuth-авторизацию и GitHub Apps без реальных запросов к api.github.com. CX Codex +1 228установок apple Локальный эмулятор Apple OIDC для разработки и тестирования авторизации через Apple. Поднимает сервер с discovery-документом, выдачей токенов и JWKS. CX Codex +1 224установок vercel Эмулирует REST API платформы Vercel на локальной машине для тестов интеграций, OAuth и деплоев. CX Codex +1 220установок slack Локально эмулирует Slack Web API для разработки и тестирования интеграций без обращения к реальному Slack. CX Codex +1 212установок microsoft Локальный эмулятор Microsoft Entra ID (Azure AD) с поддержкой OAuth 2.0 и OpenID Connect. Нужен, чтобы тестировать вход через Microsoft без реальных API — PKCE, client credentials, RS256 токены. CX Codex +1 196установок linear linear — скилл для Claude Code, тестирующий интеграции локально. Тестирует задачи, OAuth и вебхуки без реального API. CX Codex +1 113установок

Спонсоры проекта

Компании, которые помогают держать аналитику открытой