by vercel-labs OfficialFrontend & Design

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.

Installs: 186
Last 24h: —
Trending rank: —
Security: Not audited

Install

Works with every agent the skills CLI supports.

npx skills add https://github.com/vercel-labs/emulate --skill next

01
Install
Run the command in your project. The CLI asks which agents to install for.
02
Describe the task
Ask your agent for something this skill covers. It loads next automatically when relevant.
03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.

SKILL.md

The instructions your agent reads when the skill is triggered.

Next.js Integration

Q: How do I install next?

Run npx skills add https://github.com/vercel-labs/emulate --skill next in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/next/ (personal) or .claude/skills/next/ (project).

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

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:

// 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: 'test@example.com', 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:

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:

// 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:

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.)

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:

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

Incoming request: /emulate/github/login/oauth/authorize?client_id=...
Parse: service = github, rest = /login/oauth/authorize
Strip prefix: A new Request is created with the stripped path and forwarded to the GitHub service app
Rewrite response: HTML action and href attributes, CSS url() font references, and Location headers get the service prefix prepended
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`

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.

FAQ

What does the next skill do?

How do I install next?

Run npx skills add https://github.com/vercel-labs/emulate --skill next in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/next/ (personal) or .claude/skills/next/ (project).

Which AI agents can use next?

Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.

Is next safe to install?

No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.

Who maintains next?

It is published by vercel-labs in vercel-labs/emulate, and it is an official skill from the maker of the technology it covers. It has 186 recorded installs.

More from vercel-labs/emulate

View all →

emulate

vercel-labs/emulate

Local drop-in API emulator for Vercel, GitHub, Google, Slack, Apple, Microsoft, AWS, Clerk, Linear, Twilio, and other developer APIs. Use when the user needs to start emulated services, configure seed data, write tests against local APIs, set up CI without network access, or work with the emulate CLI or programmatic API. Triggers include "start the emulator", "emulate services", "mock API locally", "create emulator config", "test against local API", "npx emulate", or any task requiring local service emulation.

OfficialDevOps & Cloud542 installs

google

vercel-labs/emulate

Emulated Google OAuth 2.0, OpenID Connect, Gmail, Calendar, and Drive for local development and testing. Use when the user needs to test Google sign-in locally, emulate OIDC discovery, handle Google token exchange, configure Google OAuth clients, work with Gmail messages/drafts/threads/labels, manage Calendar events, upload or list Drive files, or work with Google userinfo without hitting real Google APIs. Triggers include "Google OAuth", "emulate Google", "mock Google login", "test Google sign-in", "OIDC emulator", "Google OIDC", "Gmail API", "Google Calendar", "Google Drive", "local Google auth", or any task requiring a local Google API.

OfficialProductivity & Automation364 installs

stripe

vercel-labs/emulate

Open the skill to read its SKILL.md instructions.

OfficialBackend & APIs271 installs

resend

vercel-labs/emulate

Open the skill to read its SKILL.md instructions.

OfficialDevOps & Cloud227 installs

aws

vercel-labs/emulate

Emulated AWS cloud services (S3, SQS, Cognito, IAM, STS) for local development and testing. Use when the user needs to interact with AWS API endpoints locally, test S3 bucket and object operations, emulate SQS queues and messages, test Cognito sign-up, sign-in, JWTs, or Identity Pools, manage IAM users/roles/access keys, test STS assume role, or work without hitting real AWS APIs. Triggers include "AWS emulator", "emulate AWS", "mock S3", "local SQS", "test IAM", "emulate S3", "AWS locally", "STS assume role", or any task requiring local AWS service emulation.

OfficialDevOps & Cloud225 installs

github

vercel-labs/emulate

Emulated GitHub REST API for local development and testing. Use when the user needs to interact with GitHub API endpoints locally, test GitHub integrations, emulate repos/issues/PRs, set up GitHub OAuth flows, configure GitHub Apps, test webhooks, or work with actions/checks without hitting the real GitHub API. Triggers include "GitHub API", "emulate GitHub", "mock GitHub", "test GitHub OAuth", "GitHub App JWT", "local GitHub", or any task requiring a local GitHub API.

OfficialBackend & APIs210 installs

Popular frontend & design skills

View category →

setup-matt-pocock-skills

mattpocock/skills

Configure this repo for the engineering skills: set up its issue tracker, triage label vocabulary, and domain doc layout. Run once before first use of the other engineering skills.

Frontend & Design1.1M installs

frontend-design

anthropics/skills

Guidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.

OfficialFrontend & Design1M installs

hyperframes-animation

heygen-com/hyperframes

All animation knowledge for HyperFrames — atomic motion rules, multi-phase scene blueprints, scene transitions, broader motion-design techniques, AND the seven runtime adapters (GSAP default, plus Lottie, Three.js, Anime.js, CSS keyframes, Web Animations API, TypeGPU). Use for any motion or animation task: pick 2-4 rules and compose, or load a blueprint, or look up runtime-specific API (e.g. GSAP eases / Lottie player / Three.js mixer). Also covers auditing an existing composition's choreography (animation map) and 24 named text-animation effects. HyperFrames-native: single paused timeline, seek-safe, deterministic.

Frontend & Design1M installs

prototype

mattpocock/skills

Build a throwaway prototype to answer a design question. Use when the user wants to sanity-check whether a state model or logic feels right, or explore what a UI should look like.

Frontend & Design999.2K installs

hyperframes-core

heygen-com/hyperframes

The HyperFrames composition contract — build one renderable project. Use for composition structure, the data- timing attributes, class="clip", tracks, sub-compositions, variables, framework-owned media playback, deterministic-render rules, and validation. Read before writing composition HTML.

Frontend & Design930.5K installs

vercel-react-best-practices

vercel-labs/agent-skills

React and Next.js performance optimization guidelines from Vercel Engineering. This skill should be used when writing, reviewing, or refactoring React/Next.js code to ensure optimal performance patterns. Triggers on tasks involving React components, Next.js pages, data fetching, bundle optimization, or performance improvements.

OfficialFrontend & Design843.1K installs

next

Install

Install

Describe the task

Review the result

SKILL.md

Next.js Integration

Install

Route Handler

Auth.js / NextAuth Configuration

Font Tracing for Serverless

Persistence

Custom Adapter (Vercel KV, Redis, etc.)

File Persistence (Local Dev)

How Persistence Works

How It Works

Limitations

Config Reference

createEmulateHandler(config)

withEmulate(nextConfig, options?)

PersistenceAdapter

Custom emulators

FAQ

More from vercel-labs/emulate

Popular frontend & design skills

`createEmulateHandler(config)`

`withEmulate(nextConfig, options?)`

`PersistenceAdapter`