CLI API and usage

Install the assembled goldar package. The binary is named goldar; from an application project, npx goldar resolves the locally installed executable. A normal application build needs only a module whose default export is an Application:

import { Application, Router } from "goldar";

export default new Application(new Router());

With the definition at src/index.ts, goldar build compiles it into dist/server.js and dist/client/client.js. The generated Node entry assembles the Hono application, serves the browser output, and starts on PORT (or 3000) when run with node dist/server.js. Files beneath project-root public/ retain their paths at the URL root and are copied beneath dist/client; public/images/logo.svg, for example, is served as /images/logo.svg. dist/goldar-manifest.json records the application entry and emitted server, script, and optional stylesheet paths. After a successful build, the CLI lists every emitted file with its uncompressed and gzip-compressed size, followed by aggregate totals.

When client.css exists beside the application entry, the generated browser entry imports it and emits the combined global and compiled-template stylesheet as dist/client/client.css. Applications reference the stable /client.css and /client.js URLs without owning a browser entry module.

goldar dev serves those same stable URLs without writing dist. Vite owns browser modules, CSS updates, public assets, HMR, and its error overlay; remaining requests fall through to the Hono application on the same port. Goldar keeps the compiler process alive and regenerates template declarations and component discovery as watched sources change.

When a server dependency changes, Goldar evaluates the next application before replacing the active one. A successful reload swaps the application and reloads connected browsers. A failed reload reports its source-mapped error while the last successful application continues serving. Client-only CSS updates do not reconstruct the server application.

Generated static handling runs after application-configured middleware and before Goldar Router routes. Authentication, headers, or other application middleware therefore still wrap assets; a terminal middleware can intentionally block them.

For custom process orchestration, create goldar.config.ts in the project root. The typed configuration helper is exported from goldar/cli.

import { defineConfig } from "goldar/cli";

export default defineConfig({
	commands: {
		build: { executable: "npm", arguments: ["run", "build:app"] },
		dev: { executable: "node", arguments: ["--watch", "src/server.ts"] },
		start: { executable: "node", arguments: ["dist/server.js"] },
	},
});

defineConfig(config) returns the same GoldarConfig; its purpose is contextual typing. A GoldarConfig requires build, dev, and start commands. Each CommandConfig supports:

• executable: required executable name or path;
• arguments: optional argument array; no shell parses or interpolates it;
• cwd: optional working directory, resolved from the project root when relative;
• env: optional string environment values merged over the current process environment.

Imports at goldar/cli intentionally expose only defineConfig, GoldarConfig, and CommandConfig. Configuration loading and process supervision are binary implementation details.

Commands

Global --root <directory> changes the project root. --config <file> selects a configuration file for the no-entry custom build, dev, and start commands. It cannot be combined with goldar build <entry> or goldar dev <entry>. Without --config, no-entry commands first check goldar.config.ts, .mts, .js, then .mjs to preserve custom lifecycle behavior. When no config exists, build and development discover exactly one of src/index.ts, .mts, .js, or .mjs. Multiple matches are rejected; keep one or pass the intended entry explicitly.

The supervisor writes state beneath .goldar and logs the production child to .goldar/start.log. It fails closed when ownership state exists but its authenticated supervisor cannot be reached; it does not signal a PID copied from stale state. start proves only process survival during the grace period, not application health, deployment readiness, or external-service availability.