GoldarDocsAlpha
Documentation menu

Getting started

Build a small server-rendered page with a typed Handlebars template, run it in Goldar’s integrated development server, and produce a standalone Node server.

Goldar is not published to npm or ready for production. This guide installs a package built from the repository so every step matches the current implementation.

Prerequisites

Application projects require Node.js 24 or newer. They do not need a Go toolchain because the Goldar package includes native compiler binaries for supported macOS, Linux, and Windows targets.

Building Goldar itself from this source repository also requires the Go version declared in compiler/go.mod.

Build the local package

From the Goldar repository root, install dependencies, build every package, and create the package archive:

npm install
npm run build
npm pack --workspace goldar

The final command writes goldar-0.0.0.tgz at the repository root. Create a separate application directory, then install that archive with TypeScript and the Node types:

npm install /absolute/path/to/goldar-0.0.0.tgz
npm install --save-dev typescript @types/node

Add the project scripts to package.json:

{
	"type": "module",
	"scripts": {
		"build": "goldar build",
		"dev": "goldar dev",
		"typecheck": "goldar sync && tsc -p tsconfig.json"
	}
}

Configure TypeScript

Create tsconfig.json:

{
	"compilerOptions": {
		"allowArbitraryExtensions": true,
		"module": "NodeNext",
		"moduleResolution": "NodeNext",
		"rootDirs": [".", ".goldar/types"],
		"strict": true,
		"types": ["node", "goldar/compiler/client"]
	},
	"include": ["src/**/*.ts", "src/**/*.hbs", ".goldar/types/**/*.ts"]
}

goldar sync reads the Props type in each template and creates compiler-owned declarations under .goldar/types. rootDirs is the TypeScript feature that makes those generated declarations act like siblings of the source templates without moving generated files into src.

Create the page

Create src/page.hbs:

---
type Props = {
	readonly title: string;
};
---

<!doctype html>
<html lang="en">
	<head>
		<meta charset="utf-8">
		<meta name="viewport" content="width=device-width, initial-scale=1">
		<title>{{title}}</title>
	</head>
	<body>
		<main>
			<h1>{{title}}</h1>
			<p>This document was rendered on the server.</p>
		</main>
	</body>
</html>

The leading block is TypeScript frontmatter. It declares the exact props accepted by the compiled template while the rest of the file remains HTML with Handlebars expressions.

Create src/index.ts:

import { Application, Route, Router } from "goldar";
import PageView from "./page.hbs";

class HomeRoute extends Route {
	render() {
		return PageView({ title: "Hello from Goldar" });
	}
}

export default new Application(new Router().addRoute("/", HomeRoute));

src/index.ts is Goldar’s conventional application entry. It must default-export an Application. An explicit entry and goldar.config.* remain available when a project needs to opt out of the convention.

See the template-language reference for the complete supported syntax, runtime semantics, and diagnostic catalog.

Run the application

Generate the template declarations and type-check the project:

npm run typecheck

Start the development server:

npm run dev

Goldar serves the Hono application and Vite browser graph on PORT, or port 3000 when PORT is not set. A template or server change triggers a reload after it compiles successfully. If a server reload fails, the last working application remains available while the diagnostic is visible.

Build production output

Build and run the generated Node server:

npm run build
node dist/server.js

The build writes the server to dist/server.js and the generated browser entry to dist/client/client.js. Links and forms continue to work without that browser script.

Place unchanged static assets under project-root public/; public/images/logo.svg becomes /images/logo.svg. Put application-wide styles in src/client.css. When a project has global or compiled template styles, Goldar emits dist/client/client.css and records it in dist/goldar-manifest.json.

Goldar does not currently inject the generated assets into your document. Reference /client.js and, when present, /client.css from the template head when the application uses browser behavior or compiled styles.

Where to go next

Read Thinking in Goldar before adding data or mutations. It explains why routes own those resources and how the pieces behave during a request. Then use the Typed Handlebars tutorial to split the page into checked, composable views.

The testing reference covers route rendering, accessibility assertions, resource replacement, and response-level tests.