Terminal
Terminal/Skill
Embeds local emulators of services like GitHub and Google inside a Next.js app, so OAuth sign-in works on every Vercel preview deployment.
By Vercel
Works with
npx skills add vercel-labs/emulate --skill nextThe @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.
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.
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 emulatorGitHub installation-token metadata is available server-side at /emulate/github/_emulate/installation-tokens.
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.
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' })
By default, emulator state is in-memory and resets on every cold start. To persist state across restarts, pass a persistence adapter.
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,
})
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.
/emulate/github/login/oauth/authorize?client_id=...github, rest = /login/oauth/authorizeRequest is created with the stripped path and forwarded to the GitHub service appaction and href attributes, CSS url() font references, and Location headers get the service prefix prependedcrypto.randomBytesinitialize to select the initial snapshot atomically across cold starts.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 |
PersistenceAdapterinterface 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.
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.