Navigate

Next.js development setup

Use Pyric with Next.js, App Router, and Turbopack.

Wrap your Next.js configuration

Import withPyric from @pyric/cli/next in your next.config.mjs:

import { withPyric } from '@pyric/cli/next';

/** @type {import('next').NextConfig} */
const nextConfig = {
  // Existing config
};

export default withPyric(nextConfig);

withPyric aliases your client-side firebase/* imports to the local browser sandbox and registers development HTTP rewrites that forward /__pyric/* requests to your local Pyric backend.

What withPyric changes

SettingWebpackTurbopack
Client firebase/* importsresolve.alias in client compilesresolveAlias
Node built-ins in client coderesolve.fallback sets fs, path and url to empty modulesunchanged
Server imports of firebase, firebase-admin, @firebase/* and aliases of themserverExternalPackagesserverExternalPackages

Each alias names a module @pyric/cli exports, such as firebase/firestore to @pyric/cli/next/internal/firestore, so both bundlers resolve it from your project’s dependencies. The aliased specifiers are firebase/ai, firebase/analytics, firebase/app, firebase/app-check, firebase/auth, firebase/database, firebase/firestore, firebase/firestore/lite, firebase/functions, firebase/messaging, firebase/messaging/sw, firebase/performance, firebase/remote-config and firebase/storage. @firebase/* packages are never aliased, so internal SDK plumbing stays untouched.

Unmodeled client subpaths (firebase/analytics, firebase/firestore/lite, firebase/functions, firebase/performance and firebase/remote-config) go to Pyric’s deferred entries. Imports resolve so module graphs load, and calling an export throws PyricDeferredApiError naming that subpath instead of crashing inside an uninitialized Firebase container or reaching production services.

Server components and route handlers keep firebase and firebase-admin external, so the @pyric/cli/register hook that pyric sandbox preloads routes them to the sandbox at runtime. withPyric also keeps every installed @firebase/* package and every npm alias of a Firebase SDK (such as "admin": "npm:firebase-admin@13") external, so the register stops those imports instead of letting the real SDK run. It finds them in the node_modules folders above the directory next dev runs in, so run next dev from your project directory. A package on that list can’t also be in transpilePackages; withPyric names it and refuses to start. Because the Next.js Edge runtime has no Node module.registerHooks loader, withPyric also refuses to start when routes export runtime = 'edge' or middleware omits runtime: 'nodejs' (PYRIC_EDGE_RUNTIME_UNSUPPORTED); switch those files to the Node.js runtime (export const runtime = 'nodejs', or export const config = { runtime: 'nodejs' } in middleware), or set PYRIC_ALLOW_UNSWAPPED_EDGE=1 if an Edge file never imports Firebase. Under pyric sandbox --hosted, firebase/database, firebase/firestore, firebase/auth and firebase/storage in server code reach the Node host as the server process’s own signed-in user. Against the browser-hosted sandbox they fail with failed-precondition; use firebase-admin in server code there.

Supervise your development server

Prefix your development start command with pyric sandbox in package.json:

{
  "scripts": {
    "dev": "pyric sandbox -- next dev",
    "build": "next build",
    "start": "next start"
  }
}

Start the supervised server with npm run dev. Pyric boots its sandbox host in the background, sets PYRIC_SANDBOX for server-side queries, and launches next dev.

pyric sandbox --persist -- next dev doesn’t save state yet: the host refuses the browser’s saves through the Next.js rewrite, so .pyric/state/state.json is never written. Track the fix in #1194.

Understand the two-server architecture

Why does Next.js run two server processes while Vite runs one? Next.js doesn’t expose Express or Connect custom middleware hooks. To preserve native compiling speed without requiring a custom server script, Pyric coordinates two processes:

Browser (http://localhost:3000)
  ├── Next.js App & UI     ──> Next Dev Server (Port 3000)
  ├── Pyric Studio (/ui)   ──> HTTP Rewrite Proxy  ──> Pyric Dev Host (Port 3473)
  └── SharedWorker Sandbox ──> Direct WebSocket    ──> Pyric Dev Host (Port 3473)
  1. Single-Origin Browser Access: Your app and Studio both load from your Next.js application port (http://localhost:3000). Next.js HTTP rewrites proxy Pyric (/__pyric/*) and Studio (/__pyric/ui/studio) through that single port. Because your app and Studio share this exact origin, they share the single browser SharedWorker that holds your active Firestore data and IndexedDB persistence.
  2. Direct WebSocket Synchrony: Next.js development rewrites proxy standard HTTP traffic but cannot forward WebSockets (Upgrade: websocket). To synchronize real-time edits between your open browser tab and server-side Route Handlers, the browser runtime bypasses the rewrite proxy to connect its WebSocket bridge directly to port 3473.

Server-side Admin SDK queries

Initialize the Admin SDK once per module, as you do in production, and call it from a route handler:

// src/app/api/status/route.ts
import { NextResponse } from 'next/server';
import { getApps, initializeApp } from 'firebase-admin/app';
import { getFirestore } from 'firebase-admin/firestore';

const app = getApps()[0] ?? initializeApp();

export async function GET() {
  const db = getFirestore(app);
  const snapshot = await db.collection('posts').get();
  return NextResponse.json({ count: snapshot.size });
}

getApps()[0] reuses the app when Next.js reloads the module. Under pyric sandbox, initializeApp() needs no credentials.

Where the call lands depends on the sandbox:

  • Node host (recommended for server code): Set your dev script to pyric sandbox --hosted -- next dev. Route handlers and server components reach the Node host directly, with no browser open. See Node host mode.
  • SharedWorker sandbox (the default): Admin calls run in your app’s browser tab, against the same data the app sees. Keep your app open at http://localhost:3000 while your server code runs. With no app tab open, or after the last one closes, they fail with unavailable and no browser tab is connected to the sandbox.

Configure or disable the runtime chip

Pass explicit options to withPyric to disable or expand the floating browser status chip during local development:

// next.config.mjs
import { withPyric } from '@pyric/cli/next';

const nextConfig = {};

export default withPyric(nextConfig, {
  runtimeChip: false, // Pass { initiallyOpen: true } to launch expanded
});

withPyric propagates your chip preference down to client runtime bundles automatically during local builds. No HTML transformations or layout component edits are required.