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 path | Input source | Output | Main constraint |
|---|---|---|---|
| Browser | Typed style elements and page class attributes | A style element in the document head | No plugins or config files |
| Standalone | CSS input plus project files | A file or standard output | Requires 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 group | Purpose |
|---|---|
| Linux arm64 and x64 | Native Linux execution with glibc and musl variants |
| macOS arm64 and x64 | Native macOS execution |
| Windows x64 | Native Windows execution |
| Oxide platform packages | Native content scanning for supported Node environments |
| Oxide WASI package | WebAssembly-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
| Trigger | Consequence | Guard |
|---|---|---|
| Browser CSS imports a stylesheet outside the embedded Tailwind entry points | The browser compiler reports an unsupported import and does not complete the build | Use 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 construction | The class may not appear in the generated CSS because the runtime sees only class attributes present in the DOM | Ensure 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 libc | The executable cannot start or cannot load its native dependencies | Select the matching release target and use the supported musl or glibc variant |
| The native file watcher cannot load during standalone or CLI watch mode | Event-based watch mode fails before watching starts | Use polling with --watch --poll when the platform watcher is not available |
| A built-in CSS export changes without matching runtime mappings | Browser or standalone builds can fail to resolve a standard Tailwind import | Update the package export and both runtime asset maps as one contract |
Key files
| File | Why to read it |
|---|---|
| packages/…/index.ts | Shows the browser lifecycle from page input to injected CSS and live rebuilds |
| packages/…/assets.ts | Shows which built-in CSS assets become part of the browser artifact |
| packages/…/package.json | Shows the browser artifact's public entry point and published file boundary |
| packages/…/tsup.config.ts | Shows the browser bundle's self-contained global output shape |
| packages/…/index.ts | Shows how the CLI, embedded assets, plugins, and bundled APIs meet inside the executable |
| packages/…/package.json | Shows the private build package, binary entry point, and bundled runtime dependencies |
| packages/…/build.ts | Shows the supported executable targets and checksum output |
| packages/…/index.ts | Shows the shared command-line build lifecycle used by the standalone entry point |
| crates/…/package.json | Shows native and WASI scanner delivery targets for Node-based runtimes |
| integrations/…/standalone.test.ts | Shows the product-level guarantees for standalone execution and plugin support |