The asset pipeline

Astro only renders pages. Every stylesheet, script, font and image on a page arrives through a separate pipeline, and almost every "weird assets" bug is a directory being written by the wrong step.

1. Who writes what

public/, tmp-assets/ and dist/ are all git-ignored per package. Never hand-edit a file in any of them, and never commit one.

2. copy-assets (.build/copy-assets.ts)

An Astro integration, configured per package in astro.config.mjs:

• On astro:config:done it deletes public/ and rebuilds it from the copies manifest (core dist, the package's tmp-assets, shared/static, favicons). Running it twice must never accumulate content — that is why it starts from a clean directory.
• It is skipped when the Astro command is sync, so astro check (and CI's type-check job) does not need built workspace assets.
• In dev it watches syncDirs and copies changed files into public/, then sends one coalesced full-reload (250 ms window, .map files ride along with their source file).
• allowDestinationFallback keeps the existing copy when the source vanishes mid-copy — @tabler/core cleaning dist/ while turbo dev starts the dependents.

Rule for watchers: copy-assets is the only writer of public/. It wipes the directory at startup, and the wipe can race a watcher that writes there directly — that was the ENOENT in #3006. Every watcher (preview's and docs' watch:css) writes into tmp-assets/css, and copy-assets syncs it into public/ via syncDirs. Do the same for anything new.

3. Ordering

turbo.json encodes the graph: @tabler/core#dev:prepare → @tabler/preview#dev:prepare → the dev tasks (docs depends on both). dev:prepare is what guarantees core/dist and preview/tmp-assets exist before a dependent package's copy-assets runs. If you add a package or an asset dependency, add the edge here too — inside a package, ordering comes from Astro's own lifecycle, not from a pre-script.

4. Traps already paid for

Do not undo these; each has a comment at the site:

• Build output must not be an Astro output dir. preview/.build/vite.config.mts writes to tmp-assets/js, not inside dist/: astro build copies public/ into dist/, so an outDir under dist/ gets re-seeded and re-copied, growing without bound across builds.
• No leading-dot output path. terser's CLI --source-map parser rejects a path segment starting with a dot (.build/out/…) with a bogus "not a supported option".
• One write per output file. build-css.ts runs sass + postcss + clean-css in-process so each file is written once, fully processed; it also skips writes when the content is unchanged, to keep watchers quiet. Do not reintroduce a step that rewrites a finished file in place — that is what shifted every source-map mapping when the banner was added afterwards (#2766).
• Two environment variables, two questions. NODE_ENV answers "dev server or build?" — Vite forces it to production for every build, including branch previews, so it can only pick unminified assets and the dev favicon. VERCEL_ENV answers "which deployment?" — production on the main hosts, preview on branch deploys, unset locally — and is the only value that may open robots.txt or anything else that must stay off on a preview. Checking NODE_ENV === 'preview' is never true anywhere. Both are in globalEnv in turbo.json; a new variable read by a build must be added there or the cache ignores it.
• Vendor copies are not pages. preview's prettify-html integration formats built HTML on astro:build:done but excludes dist/preview/ and dist/dist/, which are asset copies and contain third-party HTML that breaks the parser.

5. Diagnosing

Work down this list; each step is cheap:

1. 404 on /dist/css/tabler.css or /preview/css/demo.css — the source was never built. pnpm --dir core run dev:prepare, then pnpm --dir preview run dev:prepare.
2. Assets vanished after restarting dev — something wrote into public/ that copy-assets does not know about; it was wiped at startup. Add it to the manifest, or write it into tmp-assets instead.
3. CSS/JS edits do not appear — the watcher is not running (started astro dev alone instead of the package's dev script), or its output dir is not in syncDirs.
4. Stale content that survives a rebuild — pnpm --dir <pkg> run clean, then dev:prepare.
5. dist/ grows between identical builds — an output dir is nested inside another copy step (see the first trap).
6. CI type-check fails on missing assets — something made copy-assets run for the sync command; keep the early return.

Read the dev server's own log first: copy-assets logs public/ rebuilt from workspace assets, each fallback warning, and every reload with the file that caused it.

6. When you change the pipeline

• Verify both paths: pnpm --dir <pkg> run dev and a clean pnpm --dir <pkg> run build.
• Verify both packages when the change is in .build/ — preview and docs share those files, with different manifests.
• Run the build twice in a row and compare du -sh <pkg>/dist — equal sizes are the accumulation check.
• Confirm git status stays clean: nothing generated may become tracked.
• Do not start a build while a dev server is running (astro-dev skill).

7. Checklist

• Nothing writes into public/ except copy-assets
• New generated output lands in tmp-assets/, and is listed in the package's copies (and syncDirs when it changes during dev)
• Cross-package ordering added to turbo.json if a new dependency appeared
• Dev and clean build both verified, build run twice with stable output size
• git status clean; pnpm run type-check clean without prebuilt assets