next

# 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: '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: ```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.