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.
Static (SSG) output for `puzzle build --static` (or `output: 'static'` in puzzle.config.js). 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).
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Build ¶
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 PublicDir ¶
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 ¶
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
// Static enables the SSG prerender step (per-route static index.html output),
// the `puzzle build --static` flag. The same step also runs when
// puzzle.config.js declares `output: 'static'` — this flag is the CLI
// equivalent, and either being set is enough.
Static bool
}
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 <styles> 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) (*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 <styles> 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) ScanFormatters ¶
func (b *WatchBuilder) ScanFormatters() error
ScanFormatters refreshes the virtual formatter manifest's used built-ins.