Documentation
¶
Overview ¶
Package styles owns the CSS side of a build: running the Tailwind pipeline (constellation/doc/DOC-DECISIONS.md D12/D26) and composing the final dist/styles.css.
Composition (SPEC §3): the final stylesheet is the Tailwind output (when the pipeline is enabled) followed by the collected <style> blocks. index.html links a single /styles.css, so both layers must land in one file with the Tailwind utilities first and hand-written global CSS appended after.
The Tailwind invocation is behind the Runner interface so builds can be exercised without the real toolchain (unit tests inject a fake), while the production path shells out to the Tailwind CLI via npx.
What Tailwind v4 scans, and how the compiler stays out of its way ¶
Verified against @tailwindcss/cli 4.3.3. When the input CSS does not pin its own sources — no `@import "tailwindcss" source(…)`, no `@source` directives — the CLI registers ONE source root of `**/*` based at `--cwd`, which defaults to process.cwd(). Both runners set the child's working directory to the app root, so Tailwind walks the whole app root. The walk honors .gitignore, and there is no CLI flag for excluding a path: negative sources exist only as `@source not "…"` INSIDE the CSS, which is the user's file.
So the only lever the compiler has over that scan is what is gitignored, and the only tree it may take is its own. That is why every transient build directory now lives under a self-ignoring `<root>/.puzzle/` (internal/build/ workdir.go): measured on 4.3.3, a `.dist-staging-*` or `dist.old-*` leftover beside dist/ IS scanned even in a project whose .gitignore says `dist`, since neither name matches that rule — ten of them took the reference site's source scan from 112ms to 14s.
dist/ ITSELF is deliberately left alone. In a project that gitignores dist (the overwhelming default, and what every Puzzle template ships) it is already excluded. In a project that does not, excluding it from Go would change which sources Tailwind scans without the user asking — exactly the user-visible behavior change this must not make — and the compiler cannot do it without either rewriting the user's .gitignore, writing a .gitignore into its own shipped output, or injecting `@source not` into the user's CSS. None of those is worth it once the unignorable leftovers are gone.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Compose ¶
Compose builds the final dist/styles.css contents: the Tailwind layer first, then the collected <style> blocks. Either part may be empty. A single trailing newline is guaranteed when there is any content.
func DefaultInput ¶
DefaultInput returns the app's Tailwind input CSS path if the conventional app/styles/styles.css exists, else "" (Tailwind uses its default).
Types ¶
type NpxRunner ¶
type NpxRunner struct{}
NpxRunner runs the Tailwind CLI once per build. It resolves the CLI directly from node_modules first (running `node <@tailwindcss/cli bin>` for v4 or the `.bin/tailwindcss` shim for v3, skipping npx's resolution + a Node cold start — D27), then falls back to `npx @tailwindcss/cli` (v4) and `npx tailwindcss` (v3). If none can run — no Node/npx, offline with nothing cached — Run returns a clear toolchain-missing error so the declared pipeline fails loudly rather than producing a silently empty stylesheet.
func (NpxRunner) Run ¶
func (NpxRunner) Run(opts RunOptions) (string, error)
Run implements Runner. It writes Tailwind's output to a temp file, reads it back, and returns it as a string (keeping the single-output-file contract in Compose's hands rather than letting the CLI own dist/styles.css directly).
type ResolvedCLI ¶
type ResolvedCLI struct {
// Name identifies the invocation in logs and error messages.
Name string
// Exec is the program to run: "node", an absolute path to a .bin shim, or
// "npx".
Exec string
// Args are the leading arguments before the caller appends -i/-o/etc.
Args []string
}
ResolvedCLI is one runnable Tailwind CLI invocation: an executable plus the fixed leading arguments that precede -i/-o/--watch/--minify. Direct resolutions (`node <bin script>`, or the v3 `.bin/tailwindcss` shim) run with no npx overhead; the npx entries are the portable fallback (D27).
func ResolveCLI ¶
func ResolveCLI(appRoot string) (ResolvedCLI, bool)
ResolveCLI returns the first Tailwind CLI candidate for appRoot. It is used for user-facing status text in paths that run Tailwind one-shot per rebuild.
type RunOptions ¶
type RunOptions struct {
// AppRoot is the absolute app root (the directory holding app/).
AppRoot string
// Input is the absolute path to the input CSS entry, or "" to let Tailwind
// use its default (which still emits the utility layers).
Input string
// Production adds --minify to the CLI invocation.
Production bool
}
RunOptions parameterize a Tailwind run.
type Runner ¶
type Runner interface {
// Run generates and returns the Tailwind CSS as a string. A non-nil error
// must fail the build — a declared pipeline is never silently skipped
// (constellation/doc/DOC-BUILD-PLAN.md Phase 3).
Run(opts RunOptions) (string, error)
}
Runner produces the Tailwind CSS layer for an app. The real implementation (NpxRunner) shells out to the Tailwind CLI; tests use a fake.
type TailwindWatcher ¶
type TailwindWatcher struct {
// OutputPath is the private CSS file the child writes (-o). It must not be
// served directly; the dev loop reads it to recompose the real styles.css.
OutputPath string
// Name is the resolved CLI's human-readable identifier (for logs).
Name string
// contains filtered or unexported fields
}
TailwindWatcher manages a long-lived `tailwindcss --watch` child process. It is started ONCE per `puzzle dev` session (D27) instead of re-spawning the CLI on every rebuild (D26's one-shot path, retained for `puzzle build`). The child continuously rewrites its own private output file; the dev loop watches that file and recomposes dist/styles.css when it changes.
Lifecycle: StartWatch launches the process and returns immediately. The process is killed when the supplied context is cancelled (shutdown) or via an explicit Stop. Done() closes when the process exits for any reason — the dev loop selects on it to detect an unexpected death and fall back to one-shot composition so CSS never goes silently stale.
func StartWatch ¶
func StartWatch(ctx context.Context, opts WatchOptions) (*TailwindWatcher, error)
StartWatch resolves the Tailwind CLI (best-first: direct node_modules, then npx), starts it with --watch writing to opts.Output, and returns a handle. It errors only if the process fails to start.
func (*TailwindWatcher) Done ¶
func (w *TailwindWatcher) Done() <-chan struct{}
Done returns a channel closed when the watcher process has exited.
func (*TailwindWatcher) Err ¶
func (w *TailwindWatcher) Err() error
Err returns the process's exit error (nil until it exits; the Wait error after). A killed process reports a signal error, which is expected on Stop.
func (*TailwindWatcher) Stop ¶
func (w *TailwindWatcher) Stop()
Stop kills the watcher process (group) and closes the held-open stdin pipe. Safe to call multiple times.
type WatchOptions ¶
type WatchOptions struct {
// AppRoot is the app root (the child's working directory and the base for
// CLI resolution).
AppRoot string
// Input is the Tailwind input CSS (-i), or "" for the CLI default.
Input string
// Output is the private output CSS file (-o). Required.
Output string
// Stderr, when set, receives the child's stderr (diagnostics). Optional.
Stderr io.Writer
// CLI overrides the resolved Tailwind CLI. Tests inject a fake long-running
// command here so the watcher lifecycle can be exercised without Tailwind.
CLI *ResolvedCLI
}
WatchOptions parameterize StartWatch.