Environment variables

Dusk has two kinds, and the prefix is the rule.

Only the public names reach the browser: the DUSK_PUBLIC_ ones and the names declared in .env.public. A client file that reads import.meta.env.DATABASE_URL, or VITE_X (Dusk replaces Vite's VITE_ default with DUSK_PUBLIC_), fails the build. A public value that looks like a key or a password fails the build too ([ENV_PUBLIC_VALUE]), so a value in .env.public is a value you would put in the browser deliberately. Server variables come from the real process environment. In development, and while dusk build prerenders, dusk() loads .env.public, .env, .env.[mode], .env.local, .env.[mode].local and .env.public.local into process.env for server code, the later ones winning (a variable that is already set wins over all of them); in production there is no file loading, so use your host's environment settings, or node --env-file for a file next to the server. This order is Dusk's own: .env.local beats .env.[mode], which is the opposite of Vite's. Declare the server variables once with defineEnv; the handler validates them at startup and refuses to serve a misconfigured app, naming the variables (never their values).

import { defineEnv, EnvError } from "@shadow-js/dusk/server";

export const env = defineEnv({
  DATABASE_URL: { type: "url", protocols: ["postgres:"], secret: true },
  PORT: { type: "number", integer: true, default: 3000 },
  DUSK_PUBLIC_API_URL: { type: "url", required: false },
});

const ok = env.parse({ DATABASE_URL: "postgres://localhost/blog" });
console.log(ok.all.PORT, ok.all.DATABASE_URL);

try {
  env.parse({ PORT: "3.5" });
} catch (error) {
  if (error instanceof EnvError) console.log(error.message);
}

3000 postgres://localhost/blog
Invalid environment: DATABASE_URL (required), PORT (expected an integer)

Pass the schema as env in src/entry-server.ts (env: env); event.env.DATABASE_URL and handler.env hold the validated values. A client file imports nothing from here; it reads import.meta.env.DUSK_PUBLIC_API_URL, which the build replaces. basePath becomes Vite's base; Dusk passes it to the handler and the router.