FullStacked Runtime

FullStacked Cloud projects run on the FullStacked runtime (fullstacked npm package, version 1.0.0-alpha.1844 on this platform). A project is one bundled ES module: UI code (DOM, React) and "backend" code (Node built-ins, database drivers, process.env) run in the same JavaScript context, bridged to a native Go core. There is no separate server process: never start an HTTP server, call your own functions directly. This page lists what the runtime actually provides so code written for it works the first time.

Execution model

// index.tsx: the single entrypoint
import React from "react";
import { createRoot } from "react-dom/client";
import { App } from "./app";

const root = document.createElement("div");
document.body.append(root);
createRoot(root).render(<App />);

Running a project

npx fullstacked              # bundle and run the project in the current directory (port 9000 by default)
npx fullstacked --port 3000  # another starting port (-p is --plugin, not the port)
npx fullstacked -b           # bundle only
npx fullstacked -f script.ts # bundle and run one script file, then exit
npx fullstacked -e AUTH_TOKEN=$AUTH_TOKEN -e KEY=value

<project>/.env is loaded first, then every -e KEY=VALUE (which wins); with -f, .env is read from the current directory. In the FullStacked Cloud Client GUI the environment is injected for you.

Module resolution

The bundler maps runtime modules before npm resolution: it strips a node: prefix and a fullstacked/ prefix, then looks the name up in the runtime's module table. Consequences:

• node:fs, fs and fullstacked/fs are the same module; fullstacked/tunnel and tunnel too.
• npm packages whose name collides with a runtime module (auth, bundle, config, fetch, git, packages, parentWindow, plugin, run, test, tunnel, websocket, or a Node built-in listed on this page) cannot be imported: the runtime module is used instead.
• A named import of something a runtime module does not export (import { createServer } from "http", import { exec } from "child_process", import { copyFile } from "fs") fails the bundle with "No matching export".
• require() of these modules works in CommonJS dependencies.

Global fetch and WebSocket

At startup the runtime replaces globalThis.fetch and globalThis.WebSocket with implementations executed by the Go core.

Pitfalls of the fetch implementation:

• Content-Type is never inferred from the body: set it yourself ("Content-Type": "application/json" with JSON.stringify(...)). Avoid FormData bodies: no multipart boundary header is generated.
• response.clone() and response.formData() return null. json(), text(), arrayBuffer(), blob(), bytes() and streaming response.body work.
• A response header sent several times keeps only its last value (several Set-Cookie headers collapse to one).
• redirect: "manual" or "error" disables following redirects; the default follows them. signal (AbortController) is honored.

const res = await fetch(`${process.env.AUTH_URL}/api/v1/me`, {
    headers: { Authorization: `Bearer ${process.env.AUTH_TOKEN}` },
});

Node built-in modules

Backed by the Go core

fs details:

• Errors carry no code (no ENOENT): the message reads like error from bridge: [open /abs/path: no such file or directory]. Test with existsSync instead of catching ENOENT.
• rm and unlink of a missing path succeed silently.
• The callback forms of mkdir, rm, unlink, writeFile, appendFile, rename and cp take no options argument: fs.mkdir(p, { recursive: true }, cb) never calls cb. Prefer fs.promises or the sync forms.

Pure JavaScript

buffer (global Buffer), events, stream (promises, web, consumers), util (util/types), url, querystring, string_decoder, timers (timers/promises, global setImmediate), assert, readline (readline/promises), perf_hooks, diagnostics_channel, constants, tty, console.

Unavailable

Runtime modules (fullstacked/*)

fullstacked/tunnel

import tunnel from "fullstacked/tunnel";

interface Tunnel {
    host: string;           // hub hostname only: no scheme, no port (use process.env.TUNNELS_HOST)
    authorization?: string; // sent verbatim as the Authorization header of the WebSocket upgrade
    port?: number;          // hub port, default 443 (80 when unsecure)
    unsecure?: boolean;     // ws:// instead of wss://
    path?: string;          // hub WebSocket path (FullStacked Cloud: leave unset)
    name?: string;          // the name to register, default 8 random letters
}
tunnel.register(t: Tunnel): Promise<string>; // resolves with the tunnel name

The returned name is a virtual host recognized by net (and every TCP driver), fetch and WebSocket; for fullstacked/git, pass it as the tunnel argument (clone(url, dir, { tunnel }), pull(dir, tunnel), ...). The port you give a driver or put in a URL is ignored: the hub picks the target from the token.

How it works:

• register stores the settings under the name and opens the tunnel's first WebSocket session to wss://<host>:<port><path> in the background. It never fails on bad credentials: authorization errors surface on the first connection.
• Each registered tunnel keeps its own WebSocket sessions to the hub, authenticated once at their upgrade. Every connection to the name (socket, fetch, WebSocket) is a stream multiplexed on one of them: no handshake per connection. The runtime adds sessions under load (up to 8, 32 streams each) and closes idle ones.
• Registering the same name again with identical settings reuses its sessions; different settings replace them (the old sessions close once their streams end). The registry is shared by every project context of the runtime. Register once and reuse the name.

With FullStacked Cloud, authorization is `${process.env.AUTH_TOKEN}:${process.env.<X>_TOKEN}`: see Managed Data and Edge & LAN Tunnels.

Other modules

Checklist for agents

1. One entrypoint (index.tsx for apps with UI); create the root element in code.
2. import React from "react"; in every file that contains JSX, the entrypoint included.
3. Call your own functions, never a local HTTP server; call FullStacked Cloud with absolute URLs built from process.env.
4. Set Content-Type on every fetch with a body.
5. Use fs.promises or the sync forms listed above; copy with cp, not copyFile; check paths with existsSync.
6. Reach managed data and LAN services only through fullstacked/tunnel with ssl: false on the driver.
7. No child_process, http.request, tls, or npm packages that depend on them.