Introducing a new way to review your PRs.

Read the announcement

tailwindlabs / tailwindcss

A utility-first CSS framework for rapid UI development.

View on GitHub

19 documents · Updated Nov 20, 2026

docs / node-api-and-compilation

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:

ServiceInputResult
Compiler serviceAuthored CSS, a project base, and resolver hooksA reusable compiler that reports source rules and builds CSS from candidate strings
Scanner serviceSource rules or changed contentClass 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 onDependency behavior 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

TriggerConsequenceGuard
A CSS source(…) root does not exist or points to a fileCompiler setup fails instead of scanning an invalid rootThe Node compiler checks the source root; hosts validate directory roots when they register scanner dependencies
A config or plugin import cannot be resolvedCompilation fails and the host cannot produce reliable CSSUse 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 rebasingThe output can contain an invalid path that climbs between unrelated rootsPreserve 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 liveA rebuild can keep the old design system or plugin behaviorPerform 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 pathChanged ESM dependencies can remain stale, or startup can failPrefer registerHooks when available, fall back to register, and skip the hook in Bun
A changed content file is treated as a full compiler changeThe build loses incremental state and can recreate scanners and watchers unnecessarilyClassify content changes separately from root CSS and full-rebuild dependencies
A changed configuration or plugin file is treated as incremental contentCSS can keep the old design system or plugin behaviorMatch changes against fullRebuildPaths before using changed-content scanning
A failed full rebuild replaces the prior dependency listFixing a broken transitive file may not trigger recoveryRestore the last known full-rebuild paths after a failed rebuild
A source rule is not reflected in host watch dependenciesNew or removed matching files do not trigger a rebuildRegister scanner files and positive globs with the host's dependency or context-watch API
A watch event reaches the CLI more than once before batchingOne file change causes redundant rebuildsCollapse watched child directories and debounce collected file events
Optimization receives an invalid or missing source-map contractOutput map links can be absent or point to the wrong sourcePass the compiler map only when it exists and use the Node source-map wrapper for inline or file comments
The native file watcher cannot loadEvent-based watch mode cannot startLoad the watcher only for that mode and use polling as the supported fallback

Key files

FileWhy to read it
packages/…/package.jsonDefines the ESM, CommonJS, and cache-service package entry points consumed by hosts.
packages/…/index.tsDefines the ESM Node package boundary and module cache-hook setup.
packages/@tailwindcss-node/src/index.ctsDefines the CommonJS Node package boundary and its compatible cache-hook setup.
packages/…/compile.tsShows the compiler contract, resource loading, dependency reporting, source-root checks, resolver fallback, and stylesheet URL handling.
packages/…/urls.tsDefines the shared contract for rebasing relative CSS asset URLs when stylesheets are combined.
packages/…/index.tsDefines the core compiler result, source settings, feature flags, and repeated-build behavior.
crates/…/lib.rsShows the JavaScript-facing scanner types and operations exposed by the native binding.
crates/…/mod.rsExplains full scans, changed-content scans, and scanner state at a high level.
packages/@tailwindcss-node/src/esm-cache.loader.mtsShows how cache-bust markers reach transitive ESM imports.
packages/…/require-cache.tsDefines the CommonJS cache reset used before full rebuilds.
packages/…/optimize.tsDefines shared CSS optimization, warning, and source-map results.
packages/…/index.tsIllustrates compiler and scanner setup, full versus incremental rebuilds, watch recovery, polling, cache refresh, and output writing.
packages/…/index.tsIllustrates bounded host caching, dependency messages, and URL rebasing for inlined stylesheets in a PostCSS host.
packages/…/index.tsIllustrates per-root compiler and scanner reuse in a Vite host.