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

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/browser bundle.
  • 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

TriggerConsequenceGuard
A page omits style[type="text/tailwindcss"] and does not provide another Tailwind inputThe runtime adds the main Tailwind import, but no page-specific theme or utility source is availableAdd a marked style element when the page needs custom CSS or theme values
A marked style uses an unsupported @importCompiler creation fails and the queued build records the errorUse 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 moduleCompiler creation fails because the browser loader cannot load those modulesMove plugin or config use to a build-time delivery path
A class changes after an incremental scan and its old token remains knownThe old generated rule can remain until a full stylesheet rebuildTrigger or cause a full rebuild when removal of generated rules matters
A stylesheet update and a DOM update arrive togetherA build can be delayed while the ordered queue completes the full rebuildTreat the queue as the single build scheduler and do not run a parallel build path

Key files

FileWhy to read it
packages/…/index.tsDefines the browser runtime contract, DOM scans, rebuild types, stylesheet watchers, and output style element.
packages/…/assets.tsShows which built-in CSS assets the browser loader can resolve.
packages/…/package.jsonDefines the published browser entry and package boundary.
packages/…/index.tsDefines the compiler interface used by the browser runtime and its candidate build contract.
packages/…/compile.tsExplains how candidate names become ordered utility rules at a high level.
packages/…/ui.spec.tsDemonstrates the supported page contract through browser-level behavior, including dynamic class and stylesheet changes.