dev

package
v0.6.0 Latest Latest
Warning

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

Go to latest
Published: Aug 15, 2026 License: MIT Imports: 28 Imported by: 0

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

func Serve(root string, opts Options) error

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.

Jump to

Keyboard shortcuts

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