Tabler Asset Pipeline

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.