Develop, build, serve

npx dusk dev            # dev server: pages are rendered by your handler, edits apply on the next request
npx dusk build          # dist/client, dist/server/entry.js, dist/dusk-manifest.json, prerendered pages
npx dusk start          # production server, with the Node adapter (see below)

In development the dev server loads your server entry through Vite, adds Vite's client (hot updates, error overlay) to the HTML, and shows server errors in the overlay. dusk build builds the client, then the server, then prerenders the routes that ask for it.

Environment files: the dev server, and the prerender step of dusk build, load .env, .env.local, .env.[mode] and .env.[mode].local into process.env for your server code (all keys, server only; a variable that is already set wins). The browser still gets only DUSK_PUBLIC_ variables. The production server does not read files: serve() uses process.env as the platform set it. Security has the rules.

dusk start serves the build with the Node adapter. To write your own server instead, it is a few lines around the built handler:

import { serve } from "@shadow-js/dusk/node";
import type { Handler } from "@shadow-js/dusk/server";

// The server entry is a build output; it exports `handler` (and the same value as default).
const entry = (await import(new URL("./dist/server/entry.js", import.meta.url).href)) as {
  handler: Handler;
};

const server = await serve(entry.handler, {
  port: Number(process.env["PORT"] ?? 3000),
  host: process.env["HOST"] ?? "127.0.0.1",
  static: { dir: new URL("./dist/client/", import.meta.url).pathname },
});
console.log(`listening on ${server.url}`);

serve answers requests for built assets itself (content-hashed files get immutable caching), then hands everything else to the handler. It shuts down gracefully on SIGTERM and SIGINT. Deploy covers Docker, a proxy in front, health checks and environment variables.