NodepodOptions

Nodepod API

---

Nodepod API / src / NodepodOptions

Interface: NodepodOptions

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

Properties

allowedFetchDomains?

optional allowedFetchDomains?: string[] | null

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

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:91

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:79

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

---

env?

optional env?: Record<string, string>

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

---

files?

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

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

---

headless?

optional headless?: boolean

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

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

---

memory?

optional memory?: MemoryHandlerOptions

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

Memory optimization settings. Omit to use defaults.

---

onServerReady?

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

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

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:82

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

---

preloadEsbuild?

optional preloadEsbuild?: boolean

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

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:65

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:33

Opt-in Nodepod subsystem profiling. Disabled by default.

---

rewriteTerminalUrls?

optional rewriteTerminalUrls?: boolean

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

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:50

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:98

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:31

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

---

skipSWPreflight?

optional skipSWPreflight?: boolean

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

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:109

“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:44

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

---

watermark?

optional watermark?: boolean

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

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

---

workdir?

optional workdir?: string

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

---

workerUrl?

optional workerUrl?: string

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

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.