Skip to main content
skill CX Codex

next · vercel-labs/emulate — Claude Code skill: what it does, how to install

This skill embeds emulators in a Next.js App Router app through @emulators/adapter-next. Use it for OAuth flows, seeded test data, and persisted emulator state.

Apache-2.0 204 installs ★ 2,075 updated 2026-10-25

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add vercel-labs/emulate --skill next -a claude-code
Open on GitHub

What next does

The skill adds GitHub and Google emulators to a Next.js App Router application. It uses createEmulateHandler for a catch-all route, maps requests to each service, and accepts seed data. Routes such as /emulate/github/** stay on the app’s origin, which fits OAuth callbacks on Vercel preview deployments.

It also covers Auth.js or NextAuth provider URLs for authorization, tokens, and user info. Wrapping the Next.js configuration with withEmulate includes emulator fonts in the serverless trace. State is memory-only by default; keeping it across cold starts requires a persistence adapter, such as file storage or Vercel KV.

The server must use the Node.js runtime. Edge will fail because the emulators call crypto.randomBytes; concurrent mutations use last-write-wins semantics.

What it helps with

  • embed GitHub and Google emulators in Next.js
  • create a catch-all handler for /emulate routes
  • point Auth.js OAuth callbacks to the same origin
  • seed emulator users and repositories
  • keep emulator state across cold starts

Example prompts for the agent

  • Add GitHub and Google emulators to my Next.js App Router app with createEmulateHandler and seed data.
  • Configure Auth.js to use same-origin OAuth endpoints under /emulate/github.
  • Add persistence for emulator state and wrap the config with withEmulate.

How to install next

1Skills CLI (Vercel)

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

2Manually: put the files in place

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

Copy the whole skill folder; for one project use .claude/skills/next/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about next

How do I install next in Claude Code?

Run npx skills add vercel-labs/emulate --skill next -a claude-code. The skill is placed at ~/.claude/skills/next/SKILL.md.

What does the next skill do?

It embeds emulators in a Next.js App Router app, creates their route handler, configures OAuth endpoints, and supports state persistence through an adapter.

Does next work with the Edge runtime?

No. The emulators require Node.js because they use crypto.randomBytes. Concurrent state changes follow last-write-wins semantics.

Source text

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

Similar skills

All skills for Backend and APIs →

next by other authors comes first.

next vercel-labs This Claude Code skill turns JSON specifications into Next.js apps with routes, pages, and server-side rendering. It activates for work with @json-render/next and AI-generated multi-page apps. CX Codex +1 8,600installs next mag123c A session-start skill: reads your latest planning file, checks the git log, and tells you what to work on next. CX Codex +1 ★ 196repo stars authjs-skills gocallum authjs-skills — an agent skill that walks through Auth.js v5 authentication in Next.js: Google OAuth, email and password sign-in, environment variables. CX Codex +1 798installs next-forge official Vercel Labs A skill for Codex and ChatGPT that brings deep knowledge of next-forge, the Turborepo-based Next.js SaaS starter from Vercel. Kicks in when you touch @repo/* packages, scaffold with npx next-forge init, or edit any app in the monorepo. CX Codex GP ChatGPT +1 14installs next-cache-components official Vercel Labs next-cache-components is a Codex skill for Cache Components in Next.js 16+. It activates for PPR work, caching changes, or migrations from unstable_cache. CX Codex GP ChatGPT +1 4installs nextjs-authentication giuseppe-trisciuoglio nextjs-authentication — a skill with ready authentication patterns for Next.js 15+ App Router on Auth.js 5: providers, route protection, sessions and roles. CX Codex +1 4,000installs nextauth-authentication Mindrally nextauth-authentication guides AI agents through implementing Auth.js v5 in Next.js applications with secure session management and route protection. CX Codex +1 1,200installs oauth vercel-labs Configures OAuth providers to work with portless local development domains and resolves redirect URI mismatches. CX Codex +1 3,100installs

From the same set12

The whole set →

Project sponsors

Companies that keep this analytics open