@emulators/adapter-next 0.4.0 → 0.4.1

package/README.md

@@ -0,0 +1,120 @@
+# @emulators/adapter-next
+
+Next.js App Router integration for emulate. Embed emulators directly in your Next.js app so they run on the same origin, solving the Vercel preview deployment problem where OAuth callback URLs change with every deployment.
+
+Part of [emulate](https://github.com/vercel-labs/emulate) — local drop-in replacement services for CI and no-network sandboxes.
+
+## Install
+
+```bash
+npm install @emulators/adapter-next
+```
+
+Only install the emulators you need alongside the adapter:
+
+```bash
+npm install @emulators/adapter-next @emulators/github @emulators/google
+```
+
+## 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 } = 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' }],
+      },
+    },
+  },
+})
+```
+
+## 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 files in 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:
+
+```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 } = createEmulateHandler({
+  services: { github: { emulator: github } },
+  persistence: kvAdapter,
+})
+```
+
+For local development, `@emulators/core` ships `filePersistence`:
+
+```typescript
+import { filePersistence } from '@emulators/core'
+
+// ...
+persistence: filePersistence('.emulate/state.json'),
+```
+
+## Links
+
+- [Full documentation](https://emulate.dev)
+- [GitHub](https://github.com/vercel-labs/emulate)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@emulators/adapter-next",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "license": "Apache-2.0",
   "type": "module",
   "main": "./dist/index.js",
@@ -28,7 +28,7 @@
     "dist"
   ],
   "dependencies": {
-    "@emulators/core": "0.4.0"
+    "@emulators/core": "0.4.1"
   },
   "devDependencies": {
     "tsup": "^8",