Browser runtime
The browser runtime brings Tailwind CSS compilation into a live page. The @tailwindcss/browser package reads marked input styles and class names from the DOM, builds the CSS needed for the current page, and keeps the result current as the page changes. It is a browser delivery mode of the compiler rather than a separate styling system. See Runtime delivery, Compiler and CSS generation, and Content discovery and scanning for the related system views.
Runtime compilation model
Compiler lifecycle
The runtime separates compiler creation from CSS building. It creates a compiler from the current input CSS, then asks that compiler to build utilities for class names found in the page. This separation lets normal DOM changes add new utilities without parsing the input stylesheet again. References: packages/…/index.ts• L53-107, packages/…/index.ts• L824-859
The runtime keeps one compiler, one set of class names already seen, and one output stylesheet for the page. It sends only new class names to an incremental build because the compiler also keeps its generated result. A full build clears the browser-side class set after the input CSS changes, so the next scan represents the current page. References: packages/…/index.ts• L16-39, packages/…/index.ts• L177-229
The build queue runs rebuilds in order. This prevents two DOM events from changing the output at the same time and makes each later build see the result of the earlier one. References: packages/…/index.ts• L37-44, packages/…/index.ts• L208-229
DOM source collection
Class discovery
The runtime treats the live DOM as its content source. It visits elements with a class attribute and collects each whitespace-separated class token from the element's classList. These tokens become candidates for utility generation. References: packages/…/index.ts• L177-206
The first full build scans the whole document. Later page changes trigger an incremental build when a class attribute changes or when an element is added. The scan still checks the current document, but the runtime forwards only class tokens that it has not seen before. References: packages/…/index.ts• L180-198, packages/…/index.ts• L245-290
This model is additive during incremental updates. Removing a class does not by itself remove its generated rule; a stylesheet change causes a full rebuild that starts again from the current DOM. This keeps ordinary page updates cheap while preserving the compiler's cached utility set. References: packages/…/index.ts• L19-28, packages/…/index.ts• L764-818
Candidate-to-CSS flow
The compiler turns valid class candidates into utility rules, applies their variants, sorts the rules, and returns the complete compiled CSS. Invalid or unsupported candidates produce no utility rule. References: packages/…/compile.ts• L11-121, packages/…/compile.ts• L123-174
The runtime places the compiler output in a style element that it appends to the document head. The browser then applies the generated rules to the same DOM from which the candidates came. References: packages/…/index.ts• L31-34, packages/…/index.ts• L200-206, packages/…/index.ts• L292-294
Input stylesheet model
Tailwind stylesheet discovery
The browser package uses <style> elements with type="text/tailwindcss" as its input interface. On a full build it reads every matching element in document order and joins their CSS into one compiler input. References: packages/…/index.ts• L5-8, packages/…/index.ts• L60-74
If the collected input has no @import, the runtime adds the main Tailwind import. This gives a page with custom theme rules a useful default while still allowing an explicit import to control the CSS entry point. References: packages/…/index.ts• L76-82
The browser build resolves the built-in Tailwind stylesheet entry points from packaged CSS assets. It does not load arbitrary files from the browser, and it rejects plugin and config module loading. References: packages/…/index.ts• L109-175, packages/…/assets.ts• L1-11
Stylesheet update flow
The runtime watches each recognized input style for text, child-node, and type changes. A change schedules a full rebuild because it can alter the compiler, theme, variants, or utility rules. References: packages/…/index.ts• L232-243
The document observer also watches for new recognized input styles. It gives those additions priority over ordinary DOM changes, so one event produces a full rebuild rather than an incremental build against an old compiler. References: packages/…/index.ts• L245-285
The runtime compares the joined input CSS with the last compiled input. If the observed change does not alter the text, it reuses the existing compiler and avoids a full rebuild. References: packages/…/index.ts• L84-107
Browser-specific public interface
Script entry point
The package exposes a browser-ready global JavaScript bundle as its main and browser entry. Loading that bundle starts the runtime for the current document; the package does not expose a page-level JavaScript API for manually submitting candidates or requesting builds. References: packages/…/package.json• L2-8, packages/…/package.json• L21-27, packages/…/index.ts• L232-294
The intended page contract is therefore small:
- Load the
@tailwindcss/browserbundle. - Put Tailwind input CSS in
style[type="text/tailwindcss"]elements. - Use utility class names on the page's elements.
The runtime owns the generated style element and ignores that element when it watches for new page nodes. This prevents its own output from causing an update loop. References: packages/…/index.ts• L245-294
Browser capability boundary
The browser package supports built-in Tailwind CSS imports and CSS-driven customization. It does not support browser-side plugin or config file loading, so features that depend on those module sources belong in a build-time delivery path. References: packages/…/index.ts• L109-175
Runtime observability
Performance marks
The runtime records build stages with the browser Performance API. The marks cover stylesheet reading, compiler creation, class collection, utility building, and full or incremental build boundaries. This makes runtime cost visible in browser developer tools without changing the CSS contract. References: packages/…/index.ts• L47-50, packages/…/index.ts• L60-105, packages/…/index.ts• L180-229, packages/…/instrumentation.ts• L1-27
Change checklist
When these files or sections are changed, remember to consider these:
- Changes to the input style type or discovery rule must stay aligned with the documented page contract and the observer that tracks new styles.
- Changes to full versus incremental rebuild behavior must preserve the distinction between compiler state and the set of class tokens already sent to
build. - Changes to supported stylesheet imports must update the browser asset map and the compiler's browser-side loading boundary together.
- Changes to the generated output style element must preserve the observer exclusion or the runtime can schedule builds from its own output.
- Changes to package entry fields or bundle format must preserve direct browser script loading for the public package entry.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
A page omits style[type="text/tailwindcss"] and does not provide another Tailwind input | The runtime adds the main Tailwind import, but no page-specific theme or utility source is available | Add a marked style element when the page needs custom CSS or theme values |
A marked style uses an unsupported @import | Compiler creation fails and the queued build records the error | Use the built-in browser-supported Tailwind imports or use a build-time package for external sources |
| A marked style depends on a plugin or config module | Compiler creation fails because the browser loader cannot load those modules | Move plugin or config use to a build-time delivery path |
| A class changes after an incremental scan and its old token remains known | The old generated rule can remain until a full stylesheet rebuild | Trigger or cause a full rebuild when removal of generated rules matters |
| A stylesheet update and a DOM update arrive together | A build can be delayed while the ordered queue completes the full rebuild | Treat the queue as the single build scheduler and do not run a parallel build path |
Key files
| File | Why to read it |
|---|---|
| packages/…/index.ts | Defines the browser runtime contract, DOM scans, rebuild types, stylesheet watchers, and output style element. |
| packages/…/assets.ts | Shows which built-in CSS assets the browser loader can resolve. |
| packages/…/package.json | Defines the published browser entry and package boundary. |
| packages/…/index.ts | Defines the compiler interface used by the browser runtime and its candidate build contract. |
| packages/…/compile.ts | Explains how candidate names become ordered utility rules at a high level. |
| packages/…/ui.spec.ts | Demonstrates the supported page contract through browser-level behavior, including dynamic class and stylesheet changes. |