Node API and compilation services
The Node service layer gives command-line and build-tool integrations one way to turn Tailwind CSS input and scanned class candidates into CSS. It resolves project resources, reports files that can change the result, keeps incremental build state useful, and supplies shared output services such as optimization, source maps, and asset URL handling.
Service boundary
packages/…/index.ts is the public Node boundary for compiler work. It re-exports the compiler, optimizer, source-map, path, URL, and instrumentation services so the CLI and plugin packages can use one build model. The CommonJS boundary at packages/@tailwindcss-node/src/index.cts exposes the same services for CommonJS consumers.
The package publishes both ESM and CommonJS entry points. It also publishes dedicated require-cache and esm-cache-loader subpaths so hosts can refresh configuration modules during development rebuilds.
The boundary separates two services that work together:
| Service | Input | Result |
|---|---|---|
| Compiler service | Authored CSS, a project base, and resolver hooks | A reusable compiler that reports source rules and builds CSS from candidate strings |
| Scanner service | Source rules or changed content | Class candidates and the files or globs that support watch setup |
The compiler service is provided by @tailwindcss/node. The scanner is provided by the native @tailwindcss/oxide package. The build tool integrations combine both services with their own dependency and watch APIs.
References: packages/…/package.json• L23-52 packages/…/index.ts• L1-11 packages/…/index.cts• L1-11 packages/…/compile.ts• L22-31
Compiler service
Compilation contract
The compiler accepts CSS text or a parsed CSS tree and prepares the design system described by that input. Its result exposes the source rules, a root source setting, feature flags, and a build operation that can be called again as new candidates arrive.
The build operation keeps the compiled CSS model across calls. A consumer can scan once, pass the candidates to the compiler, and later pass only newly found candidates during an incremental rebuild. When the input uses no Tailwind feature that needs processing, the service lets the integration return the original CSS.
This diagram shows how authored CSS and discovered candidates meet at the compiler before optional output processing.
flowchart LR
CSS[Authored CSS] --> C[Compiler service]
C --> S[Source rules and feature flags]
S --> X[Scanner service]
X --> K[Class candidates]
K --> C
C --> O[Generated CSS]
O --> P[Optional optimization and source map]
References: packages/…/index.ts• L714-721 packages/…/index.ts• L824-859
Stylesheet and module loading
CSS imports and compatibility directives can refer to stylesheets, JavaScript configuration, and plugins. The Node service resolves each resource from the file that requests it and returns its resolved path, base directory, and content or module value.
Build tools can provide CSS and JavaScript resolvers. This lets aliases, package conditions, and virtual files follow the host tool's rules. When the host does not resolve a request, the Node service uses its normal Node resolution path. TypeScript configuration files can also load through the fallback module loader.
When the service inlines a stylesheet, it can rewrite relative url() and image-set() references from the imported file's directory to the build root. Absolute, external, data, fragment, and unresolved function URLs stay unchanged. Paths on different Windows drives or network shares stay absolute because a relative path between them is not valid. PostCSS uses the AST form of the same service for stylesheets that another plugin has already inlined.
References: packages/…/compile.ts• L33-64 packages/…/compile.ts• L118-195 packages/…/urls.ts• L37-96 packages/…/urls.ts• L139-166 packages/…/index.ts• L139-159
Dependency reporting
Every loaded stylesheet or JavaScript resource becomes part of the build's dependency view. The compiler reports these paths through onDependency, so an integration can watch configuration files, plugins, imported stylesheets, and their related files rather than watching only the root CSS file.
The JavaScript dependency trace follows relative imports and requires through the local module tree. A change in a transitive file can therefore request a full compiler rebuild when it changes the project design system or plugin behavior.
References: packages/…/compile.ts• L94-115 packages/…/compile.ts• L143-175 packages/…/get-module-dependencies.ts• L51-105
Scanner service
Candidate scan lifecycle
The scanner turns eligible source files into class candidate strings. Its Node-facing API supports full scans, changed-content scans, candidate positions, and the files and globs needed for watch setup.
Hosts use a full scan when they create or replace a compiler. They use a changed-content scan when the compiler and its source rules remain valid. The scanner retains its candidate set so later builds can keep candidates found in earlier scans.
References: crates/…/lib.rs• L88-190 crates/…/mod.rs• L58-92 crates/…/mod.rs• L123-220
Source selection
The compiler supplies the scanner with source rules from CSS input. An unspecified root lets the host choose its base directory. source(none) disables automatic source scanning, while explicit source(…) and @source rules add or remove paths and patterns.
The scanner combines these rules with its default file and directory limits. Explicit sources can include locations that default discovery would skip, so a project can opt into selected external or ignored content without scanning the whole workspace.
The content discovery and scanning page explains source rules and native extraction in more detail. This page treats them as the input contract for the Node services.
References: packages/…/index.ts• L174-221 packages/…/index.ts• L257-307 crates/…/sources.rs• L10-63 crates/…/auto_source_detection.rs• L4-27
Configuration discovery
CSS-led configuration
Configuration discovery starts with the CSS input rather than with a separate project-wide search. The compiler reads Tailwind directives in that input, then asks the Node loader to resolve referenced stylesheets, legacy JavaScript configuration, and plugins.
The resulting compiler records both source settings and feature flags. Integrations use those values to decide whether to create a scanner and which source paths to watch. This keeps configuration behavior tied to the CSS entry point that will consume it.
References: packages/…/index.ts• L142-179 packages/…/apply-compat-hooks.ts• L173-214 packages/…/compile.ts• L94-115
Module cache refresh
Development rebuilds must reload changed configuration and plugin modules. Relative module loads use a changing URL marker, and the Node entry points carry that marker into transitive imports through a Node module resolve hook. The ESM entry point uses import.meta.url for fallback loader registration. The CommonJS entry point uses require.resolve for the same registration path. The service also exposes clearRequireCache for CommonJS modules.
The hook is not needed in Bun because Bun also places ESM modules in require.cache. On supported Node versions, the service prefers Module.registerHooks and falls back to Module.register. These controls prevent a new CSS build from reusing an old module graph after a configuration or plugin file changes.
References: packages/…/index.ts• L13-28 packages/…/index.cts• L13-27 packages/…/esm-cache.loader.mts• L9-39 packages/…/require-cache.ts• L1-5
Incremental build state
Compiler and candidate reuse
The compiler's build method is designed for repeated use. It retains valid candidates and returns the same prepared CSS model when a rebuild adds no new usable candidate. The CLI and adapters add this retained state to a per-input context along with the scanner and dependency paths.
This shared behavior gives integrations a common rule: a changed content file can use an incremental scan, but a changed input CSS file or configuration dependency needs a full compiler setup. A full setup also refreshes the scanner's source rules because configuration can change what content is eligible.
The CLI follows this rule in both event-based and polling watch modes. It classifies changed files against the recorded full-rebuild paths, scans changed files for incremental work, and scans all current sources after a full rebuild. It replaces the watchers when the source set changes, so newly added or removed source paths become part of the next watch cycle.
References: packages/…/index.ts• L735-818 packages/…/index.ts• L278-325 packages/…/index.ts• L330-485 packages/…/index.ts• L522-679 packages/…/index.ts• L332-435
Host cache ownership
The Node package provides reusable compiler operations but does not own one global project cache. Each host owns the lifetime and key for its build context. PostCSS, Webpack, and Turbopack keep bounded contexts by input and options, while Vite keeps roots by environment and CSS entry point.
The cache key must distinguish inputs and behavior that can change the result, such as the scan base and optimization options. On a full rebuild or an error, the host replaces the relevant compiler state and clears module caches when needed. See the Vite plugin, PostCSS plugin, and Webpack and Turbopack adapters pages for host-specific lifecycle rules.
References: packages/…/index.ts• L21-49 packages/…/index.ts• L33-59 packages/…/index.ts• L67-75 packages/…/index.ts• L332-357
Shared output services
CSS optimization
Optimization is a separate Node service that takes generated CSS and returns CSS plus an optional source map. Hosts choose whether to call it and whether the output should be minified, so development builds can keep readable output while production builds can reduce it.
The service also handles supported CSS nesting and media-query transforms. It preserves an incoming map when one is supplied, which lets a host keep links back to authored CSS after optimization.
Warnings for framework-managed pseudo-selectors used by Vue and Angular are filtered because those frameworks process the selectors before they reach a browser. Other optimization warnings remain visible to the user, so real unsupported or invalid CSS still gets reported.
References: packages/…/optimize.ts• L5-31 packages/…/optimize.ts• L33-80 packages/…/optimize.ts• L119-140 packages/…/index.ts• L202-228
Source-map and diagnostic services
Source-map helpers turn compiler mappings into raw or inline map comments. Instrumentation gives hosts a shared way to count work and measure nested stages when the Tailwind debug mode is enabled. These services affect diagnostics and trace quality, not the CSS feature model.
The CLI build workflow shows how the command-line host combines these services with output writing and watch events. Plugin hosts use the same services while reporting dependencies through their own build-tool APIs.
References: packages/…/source-maps.ts• L6-59 packages/…/instrumentation.ts• L10-18 packages/…/instrumentation.ts• L93-141 packages/…/env.ts• L1-43 packages/…/index.ts• L231-267 packages/…/index.ts• L509-517
Change checklist
When these files or sections are changed, remember to consider these:
- Changes to compiler result fields or feature flags must stay aligned with scanner setup and early-return checks in every host integration.
- Changes to
onDependencybehavior must preserve full rebuild triggers for imported stylesheets, JavaScript configs, plugins, and transitive relative modules. - Changes to stylesheet URL rebasing must preserve the distinction between relative asset URLs and absolute, external, data, fragment, or function URLs across POSIX paths, Windows drives, and UNC shares.
- Changes to source-rule meaning must remain aligned between CSS parsing, the native scanner binding, and the watch paths emitted by each host.
- Changes to module cache behavior must cover ESM URL cache busting, both ESM entry modes, and CommonJS cache clearing, or development rebuilds can use stale configuration.
- Changes to Node module-hook registration must preserve Bun behavior and compatibility with the supported Node hook APIs.
- Changes to optimization or source-map output must preserve the option shape and map contract expected by the CLI and plugin packages.
- Changes to CLI rebuild classification must keep full-rebuild dependencies separate from changed content files, including recovery after a failed full rebuild.
- Changes to CLI watch setup must keep duplicate directories collapsed and batched file events debounced, or one change can trigger redundant rebuilds or miss cleanup.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
A CSS source(…) root does not exist or points to a file | Compiler setup fails instead of scanning an invalid root | The Node compiler checks the source root; hosts validate directory roots when they register scanner dependencies |
| A config or plugin import cannot be resolved | Compilation fails and the host cannot produce reliable CSS | Use the host resolver when the build tool has aliases or virtual modules; otherwise check the import base and package resolution |
| A relative asset URL crosses Windows drives or UNC shares during rebasing | The output can contain an invalid path that climbs between unrelated roots | Preserve the resolved absolute URL when the source and output roots have different drives or shares |
| A configuration or plugin dependency changes while its module cache remains live | A rebuild can keep the old design system or plugin behavior | Perform a full rebuild and clear the recorded CommonJS and ESM module caches |
| The Node hook is registered with an unsupported API or in the wrong runtime path | Changed ESM dependencies can remain stale, or startup can fail | Prefer registerHooks when available, fall back to register, and skip the hook in Bun |
| A changed content file is treated as a full compiler change | The build loses incremental state and can recreate scanners and watchers unnecessarily | Classify content changes separately from root CSS and full-rebuild dependencies |
| A changed configuration or plugin file is treated as incremental content | CSS can keep the old design system or plugin behavior | Match changes against fullRebuildPaths before using changed-content scanning |
| A failed full rebuild replaces the prior dependency list | Fixing a broken transitive file may not trigger recovery | Restore the last known full-rebuild paths after a failed rebuild |
| A source rule is not reflected in host watch dependencies | New or removed matching files do not trigger a rebuild | Register scanner files and positive globs with the host's dependency or context-watch API |
| A watch event reaches the CLI more than once before batching | One file change causes redundant rebuilds | Collapse watched child directories and debounce collected file events |
| Optimization receives an invalid or missing source-map contract | Output map links can be absent or point to the wrong source | Pass the compiler map only when it exists and use the Node source-map wrapper for inline or file comments |
| The native file watcher cannot load | Event-based watch mode cannot start | Load the watcher only for that mode and use polling as the supported fallback |
Key files
| File | Why to read it |
|---|---|
| packages/…/package.json | Defines the ESM, CommonJS, and cache-service package entry points consumed by hosts. |
| packages/…/index.ts | Defines the ESM Node package boundary and module cache-hook setup. |
packages/@tailwindcss-node/src/index.cts | Defines the CommonJS Node package boundary and its compatible cache-hook setup. |
| packages/…/compile.ts | Shows the compiler contract, resource loading, dependency reporting, source-root checks, resolver fallback, and stylesheet URL handling. |
| packages/…/urls.ts | Defines the shared contract for rebasing relative CSS asset URLs when stylesheets are combined. |
| packages/…/index.ts | Defines the core compiler result, source settings, feature flags, and repeated-build behavior. |
| crates/…/lib.rs | Shows the JavaScript-facing scanner types and operations exposed by the native binding. |
| crates/…/mod.rs | Explains full scans, changed-content scans, and scanner state at a high level. |
packages/@tailwindcss-node/src/esm-cache.loader.mts | Shows how cache-bust markers reach transitive ESM imports. |
| packages/…/require-cache.ts | Defines the CommonJS cache reset used before full rebuilds. |
| packages/…/optimize.ts | Defines shared CSS optimization, warning, and source-map results. |
| packages/…/index.ts | Illustrates compiler and scanner setup, full versus incremental rebuilds, watch recovery, polling, cache refresh, and output writing. |
| packages/…/index.ts | Illustrates bounded host caching, dependency messages, and URL rebasing for inlined stylesheets in a PostCSS host. |
| packages/…/index.ts | Illustrates per-root compiler and scanner reuse in a Vite host. |