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 / runtime-delivery

Runtime delivery

Tailwind is delivered through two runtime paths. The browser package gives a page a self-contained compiler that reacts to DOM changes. The standalone package gives command-line users a platform binary that runs the same CSS build flow without a normal Node installation.

Delivery model

Tailwind separates CSS generation from the environment that supplies input. The core compiler turns Tailwind CSS and discovered class candidates into CSS. Each delivery path supplies that compiler with a different input source and returns the result through a different output channel.

flowchart LR
  A[Tailwind CSS input] --> B[Core compiler]
  B --> C{Runtime delivery}
  C --> D[Browser bundle]
  C --> E[Standalone executable]
  D --> F[Injected page stylesheet]
  E --> G[CSS file or stdout]

The browser path is intended for pages that can compile CSS in the browser. The standalone path is intended for machines that need a simple executable rather than a Node-based package setup. The regular CLI remains the shared command-line build surface for Node users; see CLI build workflow for that flow.

Runtime targets

The browser and standalone packages optimize for different constraints. The browser bundle removes server-only extension points and embeds its built-in CSS assets. The standalone build embeds the CLI and packages the native pieces needed by each supported platform.

Runtime pathInput sourceOutputMain constraint
BrowserTyped style elements and page class attributesA style element in the document headNo plugins or config files
StandaloneCSS input plus project filesA file or standard outputRequires a binary for the host platform

References: packages/…/index.ts• L8-18 packages/…/index.ts• L60-107 packages/…/package.json• L21-30 packages/…/index.ts• L64-98 packages/…/build.ts• L22-34 packages/…/package.json• L18-25

Browser delivery

The browser package is a global, minified bundle that includes Tailwind's compiler and its built-in CSS entry points. Its package entry points resolve directly to dist/index.global.js, and the published package contains only the dist output. A page uses style elements with type="text/tailwindcss" as compiler input. If the page does not provide an import, the runtime supplies the main Tailwind import so a small page can start with only custom CSS declarations.

The runtime scans class attributes on the page and builds utilities for the classes it has not seen before. It keeps the generated CSS in a style element. DOM mutations cause either an incremental update or a full compiler rebuild when a Tailwind input style changes. A serialized build queue prevents overlapping builds while the page changes.

See Browser compilation for the browser input contract and rebuild behavior. See Standalone packaging for the executable build and release path.

Browser boundary

The browser runtime can resolve only the Tailwind CSS assets that it embeds. It supports the main stylesheet plus the preflight, theme, and utilities entry points. A request for another stylesheet or a JavaScript module fails because the browser build does not load project files, plugins, or config files.

This boundary keeps the browser artifact self-contained. It also means that browser users must express supported customization through the CSS that they place in the page rather than through the Node configuration and plugin loading path.

References: packages/…/index.ts• L109-175 packages/…/assets.ts• L1-11 packages/…/tsup.config.ts• L3-15 packages/…/package.json• L6-7 packages/…/package.json• L21-27

Standalone delivery

The standalone package turns the command-line build flow into compiled executables. The package is private and exposes its generated dist/index.mjs as the tailwindcss binary during the build and release process. The executable includes the CLI entry point, Tailwind's JavaScript APIs, built-in CSS files, and supported first-party plugins. It can therefore read a project, scan its content, and write generated CSS without asking the user to install or invoke Node separately.

The standalone build creates separate binaries for Linux, macOS, and Windows. Linux builds distinguish glibc and musl where needed. The x64 builds use baseline targets to support older processors. Each binary is hashed into sha256sums.txt so a downloaded artifact can be checked against its expected content.

Standalone integration boundary

The standalone runtime preserves the CLI's project-facing behavior. It resolves embedded Tailwind assets internally, while ordinary project paths and supported plugin packages remain available to the build. The build also excludes the executable itself from content scanning so the delivery artifact cannot add false class candidates to the generated CSS.

The standalone path is different from the published Node CLI package. The Node package exposes an executable through a package manager. The standalone package compiles that CLI into a file that carries its runtime dependencies with it.

References: packages/…/index.ts• L9-62 packages/…/index.ts• L64-98 packages/…/package.json• L4-5 packages/…/package.json• L18-34 packages/…/index.ts• L288-324 integrations/…/standalone.test.ts• L19-51

Platform artifacts

The executable set follows the build targets declared by the standalone build. The native scanner package uses optional platform packages for Node delivery and also provides a WASI build for browser-compatible use. These two packaging layers must stay aligned with the environments that the release claims to support.

Artifact groupPurpose
Linux arm64 and x64Native Linux execution with glibc and musl variants
macOS arm64 and x64Native macOS execution
Windows x64Native Windows execution
Oxide platform packagesNative content scanning for supported Node environments
Oxide WASI packageWebAssembly-based scanner delivery

References: packages/…/build.ts• L22-34 crates/…/package.json• L11-32 crates/…/package.json• L63-75 crates/…/move-artifacts.mjs• L9-36

Delivery relationships

Both paths depend on the same product contract: Tailwind CSS describes the design input, content supplies candidate class names, and the compiler produces only the CSS needed by those candidates. The difference is when and where content is observed.

In the browser, observation is live and local to the document. In the standalone executable, observation is based on project files and can continue through file watching. A change to the compiler or to the built-in CSS entry points can affect both paths, while a change to a runtime boundary may affect only one.

References: packages/…/index.ts• L177-229 packages/…/index.ts• L327-438 packages/…/package.json• L19-66

Change checklist

When these files or sections are changed, remember to consider these:

  • Built-in CSS export names in packages/…/package.json: update the browser asset imports and the standalone embedded-asset resolver together.
  • Browser compiler limits in packages/…/index.ts: keep the documented import and module boundary aligned with the bundle's actual behavior.
  • CLI entry points or imports: confirm that the standalone Bun build still statically includes the CLI and the JavaScript APIs needed by project plugins.
  • Standalone target names and native package targets: keep executable names, libc choices, optional dependencies, and release artifact names consistent.
  • Candidate scanning inputs: keep the browser DOM scan and standalone file scan from including their own generated output or executable artifacts.

Important failure modes

TriggerConsequenceGuard
Browser CSS imports a stylesheet outside the embedded Tailwind entry pointsThe browser compiler reports an unsupported import and does not complete the buildUse the supported built-in CSS entry points or move the build to the Node or standalone path
Browser content creates class names only through runtime string constructionThe class may not appear in the generated CSS because the runtime sees only class attributes present in the DOMEnsure the needed class names exist in scanned DOM content or use a delivery path that can scan source files
A standalone binary is run on an unsupported OS, architecture, or libcThe executable cannot start or cannot load its native dependenciesSelect the matching release target and use the supported musl or glibc variant
The native file watcher cannot load during standalone or CLI watch modeEvent-based watch mode fails before watching startsUse polling with --watch --poll when the platform watcher is not available
A built-in CSS export changes without matching runtime mappingsBrowser or standalone builds can fail to resolve a standard Tailwind importUpdate the package export and both runtime asset maps as one contract

Key files

FileWhy to read it
packages/…/index.tsShows the browser lifecycle from page input to injected CSS and live rebuilds
packages/…/assets.tsShows which built-in CSS assets become part of the browser artifact
packages/…/package.jsonShows the browser artifact's public entry point and published file boundary
packages/…/tsup.config.tsShows the browser bundle's self-contained global output shape
packages/…/index.tsShows how the CLI, embedded assets, plugins, and bundled APIs meet inside the executable
packages/…/package.jsonShows the private build package, binary entry point, and bundled runtime dependencies
packages/…/build.tsShows the supported executable targets and checksum output
packages/…/index.tsShows the shared command-line build lifecycle used by the standalone entry point
crates/…/package.jsonShows native and WASI scanner delivery targets for Node-based runtimes
integrations/…/standalone.test.tsShows the product-level guarantees for standalone execution and plugin support