Terminal
Terminal/Skill
Embeds local service emulators in a Nuxt app on the same origin, so OAuth works on preview deployments.
By Vercel
Works with
npx skills add vercel-labs/emulate --skill nuxtThe @emulators/adapter-nuxt package embeds emulators directly into a Nuxt app, running them on the same origin. This is useful for preview deployments where OAuth callback URLs change with every deployment.
npm install @emulators/adapter-nuxt @emulators/github @emulators/google
Only install the emulators you need. Each @emulators/* package is published independently, keeping server bundles small.
Create a named catch-all route that serves emulator traffic:
// server/routes/emulate/[...path].ts
import { createEmulateHandler } from '@emulators/adapter-nuxt'
import * as github from '@emulators/github'
import * as google from '@emulators/google'
export default defineEventHandler(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 these 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.
Emulator UI pages use bundled fonts. Wrap your Nuxt config so Nitro traces the core package assets into production builds:
// nuxt.config.ts
import { withEmulate } from '@emulators/adapter-nuxt'
export default defineNuxtConfig(withEmulate({
// your normal Nuxt config
}))
Point your OAuth provider at the emulator paths on the same origin:
const baseUrl = process.env.NUXT_PUBLIC_SITE_URL ?? 'http://localhost:3000'
export const githubOAuth = {
clientId: 'any-value',
clientSecret: 'any-value',
authorizationUrl: `${baseUrl}/emulate/github/login/oauth/authorize`,
tokenUrl: `${baseUrl}/emulate/github/login/oauth/access_token`,
userInfoUrl: `${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.
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-nuxt'
import * as github from '@emulators/github'
const storageAdapter = {
async load() { return await useStorage('emulate').getItem<string>('state') },
async save(data: string) { await useStorage('emulate').setItem('state', data) },
}
export default defineEventHandler(createEmulateHandler({
services: { github: { emulator: github } },
persistence: storageAdapter,
}))
For local development, @emulators/core ships a file-based adapter:
import { filePersistence } from '@emulators/core'
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 prependedinitialize to select the initial snapshot atomically across cold starts.createEmulateHandler(config, options?)| 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, such as import * as github from '@emulators/github' |
seed? | Record<string, unknown> | Seed data matching the service's config schema |
Options:
| Option | Type | Default | Description |
|---|---|---|---|
param | string | "path" | Named catch-all route param |
routePrefix | string | detected | Path prefix where the catch-all route is mounted |
withEmulate(nuxtConfig)Wraps a Nuxt config to include @emulators/core assets in Nitro's production trace. Call it inside defineNuxtConfig in nuxt.config.ts.
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.