Documentation
¶
Overview ¶
Package dev implements `puzzle dev`: an initial development build, a recursive fsnotify watch of the app's source tree, a debounced rebuild loop, a static file server for dist/ with history-API fallback, and SSE-based live reload. It reworks the Phase 1 prototype watcher (compiler/internal/watcher, deleted) per constellation/doc/DOC-BUILD-PLAN.md Phase 3, fixing every sin cataloged in constellation/doc/DOC-CODE-REVIEW.md §1.4:
- notifyReload() was an empty placeholder and the SSE endpoint only pinged; here every successful rebuild broadcasts a real `reload` event.
- nothing injected an EventSource client; here index.html gets the client injected at serve time (dist/index.html on disk stays clean for prod).
- new subdirectories were never watched; here Create events on directories re-add them to the watcher recursively.
- log.Fatal in the server goroutine and select{} for lifetime; here the server error returns through a channel and shutdown is graceful (SIGINT/SIGTERM → http.Server.Shutdown, SSE handlers released via context).
Styles/rebuild speed (D27, amending D26): dev drives an incremental esbuild api.Context (build.WatchBuilder) and a single long-lived `tailwindcss --watch` child (styles.TailwindWatcher) instead of a cold full build + one-shot Tailwind per change. dist/styles.css is recomposed whenever either the watcher rewrites its private output or an esbuild rebuild changes the collected <style>; the two reloads a single edit produces are coalesced. Production `puzzle build` keeps D26's one-shot path.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Serve ¶
Serve runs the dev loop for the app rooted at root (the directory holding app/app.js). It performs an initial development build, serves root/dist, watches root/app, and blocks until SIGINT/SIGTERM or a fatal server error.
A failing build — at startup or on any change — is printed (with esbuild's positioned diagnostics) but never terminates the process: whatever dist/ already holds keeps being served and the next change retries.
Types ¶
type Options ¶
type Options struct {
// Port is the TCP port the static/SSE server listens on. A busy port is not
// fatal: Serve scans upward for the next free one (see portScanLimit) unless
// StrictPort is set.
Port int
// StrictPort, when true, binds Port or fails. Pinned ports exist on purpose
// — container mappings, OAuth redirect URIs, proxy configs — and silently
// moving to a neighbour breaks whatever depends on the number.
StrictPort bool
// Open, when true, best-effort opens the app in the default browser once
// the server is listening.
Open bool
// Fixtures wires the app's app/fixtures.js (or .ts) through the detachable
// fixtures/mock runtime module (`--fixtures`, D98). The wrapper entry is
// generated once, at builder construction, and lives under <root>/.puzzle/ —
// outside every watched directory, so it cannot feed a rebuild loop.
Fixtures bool
// Profile prints phase timings for startup and each rebuild. The environment
// form is resolved inside Serve so programmatic callers get the same behavior
// as `puzzle dev --profile-build`.
Profile bool
// OnReady, when set, runs after the server's ready banner is printed.
OnReady func()
// contains filtered or unexported fields
}
Options configure Serve.