Backend bundlers & Node dev tools
When you run pyric sandbox [command...], Pyric injects NODE_OPTIONS="--import @pyric/cli/register" into your development process. This Node.js runtime loader intercepts calls to firebase-admin and firebase, transparently routing them into your local sandbox.
If your backend uses a bundler (such as Rolldown, esbuild, or tsup) during development, dependencies are compiled inline by default. When firebase-admin is bundled inline into an output file (such as dist/server.js), Node never resolves the package at runtime, and sandbox interception is bypassed.
This guide shows you how to configure your bundler to keep Firebase packages external so that pyric sandbox intercepts your backend services.
1. Import the externalisation presets
Install @pyric/cli as a development dependency if you have not already:
npm install -D @pyric/cli
Import pyricExternals from @pyric/cli/bundler:
import { pyricExternals } from '@pyric/cli/bundler';
2. Configure your bundler
Add the appropriate preset to your bundler’s external configuration.
If you use Rolldown (rolldown.config.ts)
Rolldown accepts regular expression patterns. Use the rolldown preset:
import { defineConfig } from 'rolldown';
import { pyricExternals } from '@pyric/cli/bundler';
export default defineConfig({
input: 'src/server.ts',
platform: 'node',
output: {
dir: 'dist',
format: 'esm',
},
external: pyricExternals.rolldown,
});
If you use esbuild (esbuild.config.mjs)
esbuild requires string arrays with wildcard patterns (*). Use the esbuild preset:
import esbuild from 'esbuild';
import { pyricExternals } from '@pyric/cli/bundler';
await esbuild.build({
entryPoints: ['src/server.ts'],
bundle: true,
platform: 'node',
format: 'esm',
outfile: 'dist/server.js',
external: pyricExternals.esbuild,
});
If you use tsup (tsup.config.ts)
tsup uses esbuild under the hood. Use the tsup preset:
import { defineConfig } from 'tsup';
import { pyricExternals } from '@pyric/cli/bundler';
export default defineConfig({
entry: ['src/server.ts'],
format: ['esm'],
external: pyricExternals.tsup,
});
If you use Vite for SSR or Node backend builds (vite.config.ts)
Add the pyricViteExternals() plugin. It adds every Firebase SDK your project installs to ssr.external, which Vite applies to SSR output only. That is firebase, firebase-admin, each @firebase/* package, and each npm alias of one, such as "admin": "npm:firebase-admin@13", listed by the name you import it by:
import { defineConfig } from 'vite';
import { pyricViteExternals } from '@pyric/cli/bundler';
export default defineConfig({
plugins: [pyricViteExternals()],
});
The plugin runs in vite build and never in the dev server. Your client bundle is unaffected, so browser code keeps the Firebase packages it imports. An SSR build keeps import 'firebase-admin/...', import 'firebase/...', import '@firebase/...' and aliased imports even when ssr.noExternal: true bundles every other dependency, because Vite ranks an ssr.external list above ssr.noExternal. If your config sets ssr.external: true, every dependency is already external and the plugin adds nothing.
build.rollupOptions.external applies to client and SSR builds alike, so set pyricExternals.vite there only in a config that builds nothing but Node output.
To configure a tool that takes package names rather than patterns, use pyricExternalPackages, which lists firebase-admin and firebase. Add the name of each @firebase/* package your server code imports directly, and each npm alias of a Firebase SDK, to that list yourself.
[!NOTE] For standard frontend Vite applications, use the dedicated
@pyric/cli/viteplugin instead, which handles dev-server interception automatically. You can list both plugins in one config:pyric()does not run in a productionvite build, and in a sandbox build (vite build --mode development) it resolvesfirebase/*to the sandbox entries before Vite’s SSR externalization applies.
If you use Webpack (webpack.config.js)
Webpack accepts regular expression arrays under externals:
import { pyricExternals } from '@pyric/cli/bundler';
export default {
target: 'node',
externals: pyricExternals.webpack,
};
If you use a custom predicate
For bundlers that support function-based external resolution (such as Rollup or Rolldown), use isPyricExternal:
import { isPyricExternal } from '@pyric/cli/bundler';
export default {
external: (id) => isPyricExternal(id),
};
3. Run your development server under pyric sandbox
Add your bundler watch script and server runner to package.json:
{
"scripts": {
"dev": "rolldown -c && (rolldown -c -w & node --watch dist/server.js)",
"build": "rolldown -c"
}
}
The first rolldown -c writes dist/server.js before node --watch starts, so a clean checkout with no dist starts too.
Launch your application with pyric sandbox, naming the command after --:
npx pyric sandbox --hosted -- npm run dev
pyric sandbox starts the local sandbox, then runs the command after -- with interception installed. It does not read your dev script by itself. To start the command without typing it, set command in pyric.json (CLI reference). Because firebase-admin is externalised, your server’s database, auth, and messaging operations route directly to the Pyric sandbox without requiring Google Cloud credentials or network access.
--hosted runs the sandbox in the Node host, so server code reaches it with no browser open. Without --hosted, firebase-admin calls fail with no browser tab is connected to the sandbox until a browser tab connects to the sandbox page.
4. Unbundled workflows (no bundler needed)
If your development workflow does not bundle dependencies into an intermediate file, for example when you run TypeScript files directly with tsx or native Node:
{
"scripts": {
"dev": "tsx watch src/server.ts"
}
}
No bundler configuration is required. pyric sandbox intercepts your firebase-admin imports automatically out of the box.