Enable SEA (Single Executable Application) support by supplying client/ directory as an environment variable

[Saeris]

Summary

Let @astrojs/node be told where its client/ directory is, instead of always inferring it from import.meta.url. This unblocks compiling an Astro SSR server into a single-file executable with bun build --compile or Node's --build-sea.

Background & Motivation

resolveClientDir in packages/integrations/node/src/shared.ts finds dist/client by taking import.meta.url and walking up the directory tree until it hits a path segment named server.

That inference exists for a good reason: the build bakes absolute build-machine paths into entry.mjs, so the recorded options.client is useless anywhere but the machine that produced it. Walking up is how the adapter recovers a relocatable answer. It works whenever the output keeps its directory shape.

It fails when something flattens or virtualises that path, and there are at least two real cases:

• Single-file executables. Inside a compiled binary, import.meta.url points into the runtime's virtual filesystem (B:/~BUN/root/… for Bun), which has no server segment, so the walk can never succeed and the adapter throws.

• Firebase Hosting withastro/astro#16806, labelled triage: fix pending. The Firebase CLI copies the contents of dist/server/ to the Cloud Functions root, losing the same segment.

The error message is good and was added deliberately, in #14353, where this previously hung forever walking past the filesystem root. Its suggestion — put the output in a directory named server/ — cannot help a compiled binary, because import.meta.url reports the virtual path regardless of where the executable sits on disk. I tested that.

Why single-file executables are worth supporting.

Appliance deployments (kiosks, digital signage, anything shipped to hardware someone else maintains) are much easier to install and update as one binary than as a runtime plus a node_modules tree. SEA support is new enough across the ecosystem that libraries mostly haven't met it yet, which is exactly why small assumptions like this one turn into blockers.

I patched the four lines locally and confirmed the rest works: a compiled Astro server with API routes, SSR pages and client islands served GET /api/*, GET /, and GET /_astro/*.js all at 200. The path is the only thing in the way.

Goals

• Make resolveClientDir able to accept an answer rather than only infer one.
• Keep today's behaviour exactly when no answer is supplied, error included.
• Solve the same underlying problem for deployments that flatten dist/server/, not just for compiled binaries.
• Do not require embedding client assets in the binary; shipping them as a directory beside it is fine, and a separate question.

Example

The smallest version, following the adapter's existing convention (standalone.ts already reads PORT, HOST, SERVER_CERT_PATH, SERVER_KEY_PATH and ASTRO_NODE_LOGGING):

export function resolveClientDir(options: Options) {
	if (process.env.ASTRO_NODE_CLIENT_DIR) {
		return process.env.ASTRO_NODE_CLIENT_DIR;
	}

	// ...existing walk-up, unchanged
}

ASTRO_NODE_CLIENT_DIR=/opt/my-app/client ./my-app

Two alternatives worth weighing, and I don't have a strong preference:

• An adapter option instead of an env var. Better for the Firebase case, where the adapter could set it programmatically rather than relying on the deployment to export something. It's a larger API surface.

• Emit relative paths at build time, so nothing is inferred at runtime. This is the real fix, it would resolve SEA, Firebase, and every future path-flattening deployment at once, but it changes how build output is recorded and touches more than this one adapter. Raising it because the env var is arguably papering over it.

I'm happy to open a PR if the proposed environment variable based fix is acceptable!

---

Tested with @astrojs/node 11.1.5 (current main is unchanged here), Bun 1.3.14, Node 26.1.0, output: 'server', mode: 'standalone'.

[adworacz]

+1 - I’d personally love to see support for this as well. It makes deployment and upgrading to newer node versions simple and separate from the web servers OS repo.

[florian-lefebvre]

I think getting rid of absolute paths is the best option (#1286)