build

package
v0.5.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Aug 7, 2026 License: MIT Imports: 20 Imported by: 0

Documentation

Overview

Package build drives a full `puzzle build` (constellation/doc/DOC-COMPILER-DESIGN.md §b): one esbuild api.Build pass over app/app.js with the .pzl plugin registered, then the collected global CSS and the static public/ assets are written next to the bundle. It replaces the Phase 1 prototype orchestrator (internal/compiler, deleted): no intermediate files, no runtime concatenation — the runtime is a package esbuild resolves and bundles.

Hybrid (SSG) output for `puzzle build --hybrid` (or `output: 'hybrid'` in puzzle.config.js) — the prerender + SPA-takeover mode formerly spelled 'static'. The Go compiler needs no new parser/codegen work — compiled .pzl output is already pure ViewNode-tree data — so this is entirely a downstream step: bundle a SECOND, node-platform esbuild pass whose entry imports the app's default export plus the SSG runtime, run it under node to emit one index.html per static route into the staging dir, then hand back a summary. It slots into Build() after copyPublic and before the staging→dist swap, so a prerender failure discards staging and leaves the last good dist/ exactly as it was (the same atomic-swap guarantee compile failures already get).

The true static-pages mode (`--static` / `output: 'static'`, D81) lives in prerender_pages.go and reuses the shared bundle/exec helpers here.

True static-pages output for `puzzle build --static` (or `output: 'static'` in puzzle.config.js), decision D81. Unlike the hybrid mode (prerender.go), which prerenders per-route HTML that the full SPA runtime takes over, the static mode ships content-complete HTML pages plus a SMALL per-page ES-module bundle: no router, no SPA takeover, no history API. Navigation is plain <a> page loads; the per-page script upgrades each page to an interactive document.

The Go pipeline runs the shared node prerender pass in mode 'static' (the JS side captures each page's store payload and returns an extended summary), then generates one `mountStatic` entry file per written page and runs a SECOND, browser-platform esbuild pass with Splitting over those entries into staging/_puzzle. staging/app.js is deleted (nothing references it in static mode). Like hybrid, it slots in before the staging→dist swap, so any failure discards staging and leaves the last good dist/ untouched.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Build

func Build(root string, opts Options) error

Build compiles the app rooted at root (the directory containing app/app.js) into root/dist. It returns a formatted error if esbuild reports any errors.

func FileExists added in v0.3.0

func FileExists(path string) bool

FileExists exposes the build package's historical file probe while sharing its implementation with the rest of the compiler.

func FindInstalledRuntime added in v0.3.0

func FindInstalledRuntime(start string) string

FindInstalledRuntime walks up from start for an installed Puzzle runtime and returns the absolute path to its client-runtime/index.js, or "" if absent.

func FindRuntime added in v0.3.0

func FindRuntime(start string) string

FindRuntime walks up from start looking for the in-repo runtime: a directory holding client-runtime/index.js whose package.json is named "@magic-spells/puzzle". Returns the absolute path to index.js, or "" if none.

func PkgIsPuzzle added in v0.3.0

func PkgIsPuzzle(pkgPath string) bool

PkgIsPuzzle reports whether pkgPath is a package.json for "@magic-spells/puzzle".

func PublicDir

func PublicDir(root string) string

PublicDir returns the resolved static-assets source directory (app/public, else a root-level public/), or "" if neither exists. Exported so `puzzle dev` can watch a root-level public/ tree that lies OUTSIDE the watched app/ dir (app/public is already inside it). It delegates to the same resolver the copier uses, so the watched dir and the copied dir never diverge.

func ValidatePublic

func ValidatePublic(root string) error

ValidatePublic reports an error if the app's public/ tree contains a ROOT-LEVEL file whose name collides with a reserved compiler output (app.js, app.js.map, styles.css). Such a file would be copied over the bundle/stylesheet the build just produced. Nested occurrences are allowed. It is exported so `puzzle dev` (a separate package) can revalidate on every incremental rebuild. No public/ dir is not an error.

Types

type Options

type Options struct {
	// Development disables minification (readable output for debugging and the
	// compiled-fixture test). Production (the default, Development=false) minifies.
	Development bool

	// Runner runs the Tailwind pipeline when puzzle.config.js declares it. Left
	// nil, the real npx-backed runner is used; tests inject a fake. It is only
	// consulted when a config actually enables Tailwind.
	Runner styles.Runner

	// Output is the prerender mode requested on the CLI: "" (no flag), "static"
	// (the true static-pages mode, `--static`), or "hybrid" (prerender + SPA
	// takeover, `--hybrid`). It is reconciled with puzzle.config.js `output` in
	// Build: a flag and a *different* config value is an error; either one alone
	// (or agreeing) selects the mode. Empty on both sides is the default SPA build.
	Output string

	// Fixtures wires the app's app/fixtures.js (or .ts) through the detachable
	// fixtures/mock runtime module (`--fixtures`, D98): the build bundles a
	// generated wrapper entry that installs the module before the app boots,
	// instead of bundling app/app.js directly. Off, nothing about the output
	// changes — the module is simply never imported, which is the whole
	// tree-shake. Unsupported alongside either prerender output mode.
	Fixtures bool

	// Metafile receives esbuild's JSON metafile when non-nil. It is primarily a
	// build-test seam for proving an input contributes zero production bytes;
	// normal CLI builds leave it nil and pay nothing.
	Metafile *string
}

Options configure a build.

type WatchBuilder

type WatchBuilder struct {
	// contains filtered or unexported fields
}

WatchBuilder is the incremental esbuild driver for `puzzle dev` (D27). It holds a persistent api.Context so each Rebuild reuses esbuild's parse/resolve caches — only changed inputs are re-read — instead of the cold full pass that build.Build does for production. It owns ONLY the JS bundle and the static public/ copy; the dev loop composes dist/styles.css itself (Tailwind comes from the warm --watch child, not a one-shot per rebuild).

The single Plugin instance lives for the context's lifetime, so its <style> collector is shared across rebuilds — that is what makes CSS() reflect the current graph (with the plugin's set-or-delete + deleted-file pruning keeping it honest as files change; see plugin.CSS).

func NewWatchBuilder

func NewWatchBuilder(root string, opts WatchOptions) (*WatchBuilder, error)

NewWatchBuilder creates the incremental builder for the app rooted at root (the directory containing app/app.js). It validates the entry point and constructs (but does not yet run) the esbuild context. Always development mode: readable, unminified output.

func (*WatchBuilder) CSS

func (b *WatchBuilder) CSS() string

CSS returns the collected <style> blocks from the most recent rebuild.

func (*WatchBuilder) Dispose

func (b *WatchBuilder) Dispose()

Dispose releases the esbuild context. After Dispose the builder must not be used.

func (*WatchBuilder) Rebuild

func (b *WatchBuilder) Rebuild() error

Rebuild runs one incremental esbuild pass (reusing caches) and re-copies the static public/ assets. It returns a formatted error if esbuild reports any — the JS bundle is written by esbuild directly (Write: true). Styles are NOT touched here; the caller composes dist/styles.css from CSS() plus the Tailwind layer.

func (*WatchBuilder) ScanUsage added in v0.3.0

func (b *WatchBuilder) ScanUsage() error

ScanUsage refreshes the virtual formatter manifest and feature defines. The formatter manifest reads plugin state during each Rebuild. Defines are frozen into an esbuild context, so replace that context only when one of the booleans changes; ordinary rebuilds keep the incremental graph warm.

type WatchOptions added in v0.3.0

type WatchOptions struct {
	// Fixtures bundles the generated `--fixtures` wrapper entry instead of
	// app/app.js (D98), installing the fixtures/mock module before the app boots.
	// The wrapper is generated ONCE here, at construction, and left in place for
	// the process lifetime — it lives under <root>/.puzzle/, which is outside every
	// watched directory and pruned from the usage scan, so writing it can never
	// trigger a rebuild.
	Fixtures bool
}

WatchOptions configure the incremental dev builder.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL