NodepodOptions

Interface: NodepodOptions

Properties

allowedFetchDomains?

optional allowedFetchDomains?: string[] | null

domains allowed through the cors proxy. merged with built-in defaults (npm, github, esm.sh etc). pass null to allow everything

enableSharedArrayBuffer?

optional enableSharedArrayBuffer?: boolean

Defined in: src/sdk/types.ts:107

set to false to force SAB off even if the runtime has it. useful for envs without COOP/COEP or for testing partial mode. when off: execSync/spawnSync throw on call, threaded wasi modules (rolldown, lightningcss, tailwind-oxide) refuse to load, and cross thread vfs reads fall back to async message passing. defaults to true.

enableSnapshotCache?

optional enableSnapshotCache?: boolean

Defined in: src/sdk/types.ts:95

Cache installed node_modules in IndexedDB for faster re-boots. Default: true.

env?

optional env?: Record<string, string>

Defined in: src/sdk/types.ts:42

files?

optional files?: Record<string, string | Uint8Array<ArrayBufferLike>>

Defined in: src/sdk/types.ts:35

headless?

optional headless?: boolean

Defined in: src/sdk/types.ts:49

Headless mode: no terminal/preview UI required. Defaults serviceWorker and watermark to false (can still be overridden). Implied when importing from @r1ck404/nodepod/headless.

memory?

optional memory?: MemoryHandlerOptions

Defined in: src/sdk/types.ts:93

Memory optimization settings. Omit to use defaults.

onServerReady?

optional onServerReady?: (port, url) => void

Defined in: src/sdk/types.ts:89

Called after a server’s reported preview URL is ready to navigate to.

Parameters

port

number

url

string

Returns

void

packageStore?

optional packageStore?: "auto" | "memory" | "opfs"

Defined in: src/sdk/types.ts:98

Package snapshot backend. “auto” currently prefers IndexedDB; explicit “opfs” canaries packfiles and falls back automatically.

persistence?

optional persistence?: PersistenceOptions

Defined in: src/sdk/types.ts:41

Save the project filesystem and restore it on the next boot with the same id. node_modules is not saved; it is reinstalled from package.json (normally straight from the package cache).

preloadEsbuild?

optional preloadEsbuild?: boolean

Defined in: src/sdk/types.ts:132

Start downloading + compiling esbuild-wasm (~10MB) during boot so it’s ready by the time installs or builds need it. The download overlaps Service Worker registration and package installs. Default: false; the engine otherwise initializes automatically on first use.

previewOrigin?

optional previewOrigin?: PreviewOriginOption

Defined in: src/sdk/types.ts:72

Hostname used for virtual server previews. The default, "auto", uses http(s)://{instanceId}-{port}.localhost:<host-port> on local loopback pages and falls back to /__virtual__/... elsewhere.

Production hosts can provide a template such as https://{instanceId}-{port}.preview.example.com. Set false to always use path URLs.

profiler?

optional profiler?: ProfilerOptions

Defined in: src/sdk/types.ts:34

Opt-in Nodepod subsystem profiling. Disabled by default.

reservedHostPaths?

optional reservedHostPaths?: string[]

Defined in: src/sdk/types.ts:81

Same-origin paths that belong to the host application and must never be served by a pod, even when a preview has claimed an enclosing path such as /. Use this for host documents embedded alongside previews (a runtime host page, its module URLs). Entries ending in / are prefixes; others match exactly. Requests issued by a document at a reserved path bypass pod routing as well.

rewriteTerminalUrls?

optional rewriteTerminalUrls?: boolean

Defined in: src/sdk/types.ts:87

Visually rewrite loopback URLs in Nodepod-owned terminals to their real preview URLs. Raw process stdout/stderr remain unchanged. Defaults to true.

serviceWorker?

optional serviceWorker?: boolean

Defined in: src/sdk/types.ts:57

Set to false to skip SW registration (SSR, Node tests, or hosts that don’t need preview iframes / virtual HTTP servers). Defaults to true when navigator.serviceWorker is available, or false in headless.

sharedVFSBufferSize?

optional sharedVFSBufferSize?: number

Defined in: src/sdk/types.ts:114

capacity in bytes of the SharedArrayBuffer-backed fs mirror used by workers and WASI modules. default is 256 MiB — enough for typical app dependency trees including WASM toolchains. must be set before boot because a SharedArrayBuffer cannot grow after workers receive it.

shell?

optional shell?: ShellOptions

Defined in: src/sdk/types.ts:32

Shell policy shared by the pod’s terminal and spawned processes.

skipSWPreflight?

optional skipSWPreflight?: boolean

Defined in: src/sdk/types.ts:62

Skip the HEAD preflight on the SW URL. Use if your host blocks HEAD, requires auth on assets, or otherwise trips the check.

spawnSnapshot?

optional spawnSnapshot?: "full" | "lean"

Defined in: src/sdk/types.ts:125

“lean” excludes node_modules/.npm/.cache from per-spawn VFS snapshots; workers fetch those files on demand over a synchronous fs proxy. Cuts per-process memory roughly by the size of node_modules. Requires SharedArrayBuffer (COOP/COEP) — silently falls back to “full” without it. Default: “lean” when SharedArrayBuffer is available, otherwise “full”.

swUrl?

optional swUrl?: string

Defined in: src/sdk/types.ts:51

URL of the nodepod service worker. Defaults to /__sw__.js.

watermark?

optional watermark?: boolean

Defined in: src/sdk/types.ts:91

Show a small “nodepod” watermark link in preview iframes. Defaults to true.

workdir?

optional workdir?: string

Defined in: src/sdk/types.ts:43

workerUrl?

optional workerUrl?: string

Defined in: src/sdk/types.ts:139

URL of the process-worker bundle asset (dist/worker.js). When the asset is reachable, workers boot from it instead of the copy embedded in the library string, saving parse time and heap. Auto-detected next to the built library when omitted; the embedded copy remains the fallback.