PostCSS processor
PostCssProcessorPlugin is a Processor (see /dev/plugin-pipeline) that transforms stylesheets. Its single stylesheet capability matches *.css and is narrowed by a filename filter, default /\.css$/. It declares no Sass or Less extension, so those files are not stylesheets in an app that registers it, and an app can register only one stylesheet Processor (see /dev/plugin-pipeline). It is a transform and an invalidation hook only: core owns the cache, the prewarm, the watch queue, the dependency map, the dev writes and css-update (Development lifecycle).
Where core calls the transform
Core reaches the Processor through one function, transformStylesheet(css, file), from three places. It returns { css, dependencies }: the dependencies are the file of each PostCSS message of type dependency, which postcss-import sends for every stylesheet it inlines, whatever the form of the @import (a layer(), a media query, an unquoted url(), an alias). Tailwind's own dependency and dir-dependency messages are not dependencies: they name the files and directories it scanned for class names, stylesheets included, which would make each scanned stylesheet look like a partial of the Tailwind entry. transformWithPostcss returns them apart as contentSources (scanned files, and each directory with its glob), the plugin keeps them per stylesheet, and a change to scanned content reaches the stylesheet through invalidateStylesheets.
- Asset pipeline: for every
.cssdependency, core callstransformStylesheeton the one Processor that declares astylesheetcapability, when that capability matches the file. This is howconfig.dependencies.stylesheetsand content stylesheets get processed. Core then inlines the relative@imports the output still has (inlineStylesheetImports), so plain CSS with no Processor works once it is written todist: the partial's CSS replaces the@import, wrapped in@layer,@supportsand@mediablocks for its conditions, its relativeurl()references are rebased onto the stylesheet, remote@imports and the first@charsetmove to the top, and a partial imported more than once is inlined once, at its last import, as the cascade and Lightning CSS order it. When the Processor already inlined them there is nothing left to do. An@importthat names a missing file is left as written with a warning that names the importing file, and in development the stylesheet is rebuilt when the file appears; a bare specifier that names no sibling, such as a package, is left for the Processor, and only a.cssfile that is not a dotfile is inlined. The partials join the stylesheet's dependencies, so an edit to one rebuilds the stylesheet, with or without a Processor. For a file stylesheet, core then resolves each relativeurl()andimage-set()string in the output from the real directory of the source file, emits the file it names todist/client/assetsunder a content hash, and rewrites the reference relative to where the stylesheet is written, or root-relative when it is inlined (emitStylesheetReferences). A reference to a missing file is left as written with a warning, since Tailwind can generate aurl()from a class it finds in content. Aurl()that holds another function, such asurl(var(--hero)), names no file and is skipped without a warning. Only a font (woff2,woff,ttf,otf,eot), image (png,jpg,jpeg,gif,webp,avif,svg,ico,bmp,apng,jxl,tif,cur) or media file (mp4,webm,mov,ogg,mp3,m4a,wav) is copied, never a dotfile; a reference to any other file is left as written with a warning, so a reference such asurl(../../.env)cannot publish a secret. The rule goes by file type, not location, because in a monorepo the app's packages sit outside its folder and a package may name a sibling dependency's files. A package stylesheet that discovery found (import 'some-lib/style.css', an asset withfromPackage) skips this step: core only rewrites itsurl()references and inlines its@imports, so Tailwind and the preset plugins never run on third-party CSS (see /dev/pages-layouts-components). - Stylesheet imports:
import styles from './card.css'gets the module core'scompileStylesheetModulereturns,export default "<css>"with this Processor's output, in server builds, browser bundles and the dev transform server alike (see /dev/build-pipeline). The Processor contributes no build plugin for it.
Per-environment handling
| Environment | Behavior |
|---|---|
server and browser builds | No plugin from this Processor; core calls transformStylesheet for each imported stylesheet. |
| Development | Core's development stylesheet service calls transformStylesheet to prewarm and to rebuild after an edit, and invalidateStylesheets for a template or script edit. setup() does nothing. |
| Production runtime | Nothing runs until a stylesheet is processed; nothing is written to distDir from here. |
Config loading
The plugin list loads lazily, once, on the first transformStylesheet (ensurePostcssPlugins); a failed load is dropped so the next stylesheet retries. Config finalization does not load the plugins, so a build that starts before setup() and an app without stylesheets both work.
Resolution order in resolvePostcssPluginsFromSources:
postcss.config.{js,cjs,mjs,ts}inrootDir, imported dynamically. It may exportpluginFactoriesandplugins(array or record). An import error is logged and yields no config.- Otherwise
options.pluginsoroptions.pluginFactories. - Otherwise a warning and an empty plugin list.
Note that a config file wins over options.
transformWithPostcss runs the plugins and the transformOutput hook and returns the CSS with its dependencies; PostCssProcessor.processStringOrBuffer returns only the CSS. A PostCSS error rejects, and a CssSyntaxError names the file, line and column in its message. Nothing returns empty CSS for a failed stylesheet.
Errors and warnings
Where the error goes depends on who called transformStylesheet:
| Caller | On a PostCSS error |
|---|---|
| Core asset pipeline | applyStylesheetProcessors lets it propagate, the asset rejects processDependencies, and ecopages build fails without writing a stylesheet for the file (see /dev/asset-processing). In ecopages dev a Page request instead renders with the stylesheet's last good output, or without its link when none compiled, and the error shows in the overlay. |
Core compileStylesheetModule, for a stylesheet imported with a binding | A server build or browser bundle fails, so ecopages build fails. The dev transform server shows the error and keeps serving the stylesheet's last compiled module until a save compiles again (/dev/dev-server). |
| Development watch | Core's development stylesheet service logs it and calls bridge.error, which shows the error overlay. Its cache and the file under distDir/assets keep the last good output, and no css-update is sent. The file is remembered as failed, so the first save that succeeds sends css-update even when its output equals the last good one, which clears the overlay; the byte-change check applies again after that. |
| Development prewarm | Logged per file and skipped, so one broken stylesheet does not stop the dev server from starting; the watcher reports it again when the file changes. A partial that fails on its own while another stylesheet imports it is not logged. |
Recovery needs no restart: core caches no failed asset (the asset service stores only successes and drops its in-flight entry), so in development a Page requested while the stylesheet is broken renders with the last good output and renders the fixed one after the next good save.
PostCSS result.warnings() are logged with the file, line and column. A stylesheet goes through several processing passes (once per Page that links it, linked and inlined, and once per build that imports it as text), so warnStylesheetOnce logs a warning once per stylesheet and message until the stylesheet's contents change. Core's warnings about a url() that names a missing or non-copyable file use the same function.
Presets
src/presets/ holds tailwindV3Preset() and tailwindV4Preset({ referencePath }). Both return plugins for immediate use and pluginFactories, with postcss-import (app-aware, resolving from the app root), nesting, Tailwind, autoprefixer and cssnano. createAppAwarePostcssImport first drops every @import of a stylesheet that a later @import imports again, in the entry and in the partials it reaches, so a stylesheet imported twice is inlined once, at its last import, as the cascade, core and Lightning CSS order it (postcss-import alone keeps the first). It then runs postcss-import and, through core's rebaseStylesheetReferences and its CSS scanner, rebases the relative url() references of every declaration it inlined from another file onto the importing stylesheet, so url(files/font.woff2) from @import '@fontsource/inter' still names the package's file when core resolves it from the app's stylesheet. Both ends are real paths, since postcss-import reads an imported file through its symlinks.
Factories exist because Tailwind keeps internal caches in long-lived plugin instances. invalidateStylesheets(files) is the Processor's invalidation hook. Core calls it for a batch that changed any file that is not a stylesheet. It rebuilds the plugin list from the factories, so newly used classes are found, and names the stylesheets whose content sources match a changed file: a file in a scanned directory that the directory's glob accepts (Tailwind v4 scans the files git does not ignore, v3 the files its content globs name), or a scanned file. A lockfile, or a file in a directory Tailwind does not scan, rebuilds nothing. A stylesheet has content sources once it has been transformed, and dependencyEntryPaths, when set, limits the answer to those stylesheets. Paths are compared as reported, so a project reached through a symlink must be addressed by the real path the scanner reports.
The v4 preset also sets dependencyEntryPaths: [referencePath] and a transformInput that rewrites @import 'tailwindcss' to the reference file, or adds @reference to files that use @apply, so component stylesheets see the theme. The @reference goes after the leading @charset, @layer and @import statements, since postcss-import inlines an @import only while every statement before it is one of those. It skips the reference file itself and files that already reference it.
Development lifecycle
Core's DevelopmentStylesheetService (dev/stylesheets/development-stylesheet.service.ts) keeps the stylesheets current for whichever stylesheet Processor the app registers, so this package holds no cache, graph or queue of its own. When the Project Watcher subscribes, the service processes every stylesheet the Processor owns in srcDir, except the public directory, and records each output and the dependencies its transform reported. For each watcher batch, queued behind the previous one:
- A changed file rebuilds every stylesheet whose transform read it, so an edit to an
@importpartial rebuilds the stylesheets that inline it. The changed stylesheet is rebuilt itself too, since a Page may link a partial as well. A partial that fails on its own is not reported: it may only compile inside the stylesheets that import it, and those report their own errors. - The changed files that are not stylesheets go to
invalidateStylesheets. - A rebuild writes the output at its source-relative path under
distDir/assetsthrough core'swriteSourceRelativeStylesheet, so the files its relativeurl()references name are emitted after an edit as on first load. Only stylesheets insidesrcDirare written; the service runs only in development, so production writes nothing. It sendsbridge.cssUpdate(file)only when the bytes changed, or on the first success after a failure.
The bridge sends a css-update message with the exact href the stylesheet was delivered at, and the client refreshes that one link; see /dev/hmr-watcher-invalidation and /dev/hmr-client. A stylesheet whose output changed while its own bytes did not, such as one whose partial changed, is then planned as changed, so a module that imports it as text is hot-updated by core's HMR and the server modules that embed it are rebuilt (/dev/hmr-strategies).
Contract tests
@ecopages/core/processor/contract exports stylesheetProcessorContract({ createProcessor }), the cases every first-party stylesheet Processor runs: the dependencies a transform reports drive rebuilds of the server modules that embed the stylesheet and of the stylesheet in development, a transform that throws fails the build, and a failure in development keeps the last good output until a save fixes it, for a watcher save and for a Page request, where a stylesheet that never compiled renders without its link and a production build still fails. That plain CSS passes through with no Processor is core's own test, since it checks no Processor. Each case is { name, run }, so any runner can register them; this package runs them with postcss-import in src/test/stylesheet-processor-contract.test.ts.
Sources
This page describes the code below.
packages/processors/postcss-processor/src/plugin.tspackages/processors/postcss-processor/src/postcss-processor.tspackages/processors/postcss-processor/src/postcss-config-loading.tspackages/processors/postcss-processor/src/postcss-import-app-aware.tspackages/processors/postcss-processor/src/presets/packages/core/src/plugins/processor.tspackages/core/src/plugins/stylesheet-kinds.tspackages/core/src/assets/asset-processing-service/processors/stylesheet/stylesheet-processor-pipeline.tspackages/core/src/assets/asset-processing-service/processors/stylesheet/css-scanner.tspackages/core/src/assets/asset-processing-service/processors/stylesheet/app-stylesheet-imports.tspackages/core/src/assets/asset-processing-service/processors/stylesheet/file-stylesheet.processor.tspackages/core/src/assets/asset-processing-service/processors/stylesheet/source-relative-stylesheet.tspackages/core/src/assets/asset-processing-service/processors/stylesheet/stylesheet-warnings.tspackages/core/src/dev/stylesheets/development-stylesheet.service.tspackages/core/src/processor-contract.ts