Custom Bundles

Ship only the Reactive CSS capabilities your project uses. Analyze your stylesheets or choose features, let the resolver add what they require, and build one file with the reactive-css CLI.

Since 0.8.0 the runtime is modular; 0.9.0 has 15 features. Reactive CSS can analyze your stylesheets, determine which capabilities they need, and build a production bundle with those features and everything they depend on.

How it works

From your CSS to one file.

1. →Your CSSYou pass the stylesheets and pages you serve. The analyzer reads only those inputs.
2. →Feature analyzerreactive-css analyze compiles them with the library’s own compiler and lists the Reactive CSS features they use. Native CSS is left alone.
3. →Dependency resolverThe core is always included. Each feature adds what it requires: focus adds events.
4. →Custom bundlereactive-css.min.js, one file you host yourself, and a manifest that records the version, features and sizes.

For this stylesheet:

.tabs { --tab: state(1); }.tab:on(click) { --tab: set(2); }.panel:when(--tab == 2) { display: block; }

the analyzer reports:

Stylesheets analyzed: 1Features used: events, conditionsRecommended: --features events,conditions

Quick start

Your first custom bundle.

npx -p @reactivecss/core -p esbuild reactive-css build --features conditions,focus --out public/reactive-css.min.js

Features and dependencies

Every bundle contains the core.

Each other feature is a real module with the requirements below. Selecting a feature adds what it requires; a feature that is only useful with another one is never added automatically. The Bundle Builder makes the same selection with sizes.

• A counter needs events for its :on(click) rules and text for content: var(--count), over the core.
• Focus requires events. focus: moves focus only after a trusted user action, which the event dispatcher records. Form bindings record it too, so forms is useful with focus but not required. focus: when(--open) also needs conditions for when(), which the analyzer adds; focus: var(--open) does not.
• Gestures require events. Drag rules reuse the event dispatcher and the event-time evaluator. gestures is the only feature with pointer-gesture code, so form and event bundles never carry drag.
• Persistence stands alone. persist needs neither forms nor events: a persisted state works in a core-only page.
• Forms do not need drag or focus, and blur needs only the core.
• History as values vs operands. previous(--x) and direction(--x) as operands of a condition, such as :when(direction(--n) > 0), are part of the core. The history feature adds them as values, as in content: previous(--n), and adds :changed().
• Profiles are named selections, not separate builds: basic, forms, stateful-ui, interactive, dynamic and full. interactive is new in 0.9.0: events, gestures, persistence, conditions, attributes and text.

Missing something? You’ll know

A custom bundle still recognizes all Reactive CSS syntax. When a stylesheet uses a feature the bundle does not contain, the browser ignores that declaration, as it would without the library, and the library adds one entry to ReactiveCSS.diagnostics.

1. →The stylesheet uses.count output { content: var(--n); }
2. →The bundle containscore, events, conditions, focus
3. →ResultThe native content stays, no DOM text is written, and one diagnostic names the feature

A minified bundle reports the diagnostic as a code with its values:

inline <style> #1: RCSS-P001⟦content: var(…) as DOM text⟧⟦text⟧⟦text⟧

Decode it offline with the CLI, or load the development bundle reactive-css.js, which logs the full text:

inline <style> #1: content: var(…) as DOM text is not included in this bundle (feature "text"); build a bundle with it (reactive-css build --features text) or use the full bundle

Fix it by adding the feature and building again:

npx -p @reactivecss/core -p esbuild reactive-css build --features events,conditions,focus,text --out public/reactive-css.min.js

• random() and element() also exist in native CSS, so for them the entry is a note rather than a warning.
• ReactiveCSS.describe().bundle lists the features a bundle contains.
• After switching a site to a custom bundle, open its pages and check ReactiveCSS.diagnostics.

Analyzer

Let your CSS tell you what it needs.

The analyzer compiles stylesheets with the library’s real compiler and lists the features they use. It handles nested functions, @media, @layer, comments, strings, and native look-alikes such as element(#id), which it does not count. With --build it builds the recommended bundle in the same step.

npx -p @reactivecss/core -p esbuild reactive-css analyze public/ --build public/reactive-css.min.js

When something is missing from its input, it says so and recommends the full runtime (the warning names the file by its absolute path):

@import url("theme.css");.a { --n: state(0); }.a:on(click) { --n: increment(1); }

Stylesheets analyzed: 1Features used: eventsRecommended: the full runtime (analysis incomplete (see notes)).warning [import-not-followed] …/imp/styles.css: @import rules are not followed: analyze the imported files too.

With --json, each file also lists its 0.8 declarations (on:, text:, attr:) under legacy, with their 0.9 form. See Migrating from 0.8.

To try it on your own CSS without installing anything, paste it into the Bundle Builder. It runs the same compiler in the page, without sending your CSS anywhere.

Bundle sizes

Smaller by design. Measured in bytes.

Only the builds in the release report have exact sizes. Any other combination gets its size when you build it: the CLI prints it and writes it to the manifest. Per-feature numbers do not add up, because features share code with the core and with each other. The core is the largest part: it holds the whole compiler, which recognizes every syntax so that missing features can be reported, plus the stylesheet rewrite, the state engine and the scheduler.

Advanced configuration

Reference for the build tools.

error [unknown-feature]: Unknown feature "evnts". Did you mean "events"? Features: core, events, gestures, persist, conditions, nth-var, history, forms, text, attributes, focus, blur, values, dynamic, geometry.

import { build } from '@reactivecss/core/bundle';const result = await build({ features: ['events', 'conditions', 'focus'], outfile: 'public/reactive-css.min.js' });if (!result.ok) throw new Error(result.errors.map((e) => e.message).join('\n'));

error [conflict]: "events" is excluded, but "focus" requires it. Remove "events" from the exclusions or "focus" from the features.

{  "name": "reactive-css",  "version": "0.9.0",  "format": "iife",  "minify": true,  "features": ["core", "events", "conditions", "focus"],  "requested": ["events", "conditions", "focus"],  "added": [],  "excluded": ["gestures", "persist", "nth-var", "history", "forms", "text", "attributes", "blur", "values", "dynamic", "geometry"],  "optionalMissing": [{ "id": "forms", "usefulFor": "focus" }],  "sizes": { "minified": 85540, "gzip": 29370, "brotli": 26343 }}

Hosting

Host it yourself.

npm package

The full and compact bundles and the CLI, from the package.

CDN

The full and compact bundles, version-pinned, from jsDelivr or unpkg.

Custom bundle

Built on your machine and served from your site. It has no CDN URL.

<link rel="stylesheet" href="/styles.css"><script src="/reactive-css.min.js"></script>

• Rebuild it when you upgrade the package. Bundles from different versions are not interchangeable.
• Rebuild it when your stylesheets start using a new feature, or run the analyzer in your build step.

The distributions and the CDN status are in the Installation guide.

FAQ

Do I need a custom bundle for a small project?

No. Start with the full bundle. It needs no tooling. Build a custom one when its size matters.

What happens when I start using a new feature?

The declaration is ignored and a diagnostic names the feature to add. Build again with it, or run the analyzer in your build step.

Can the analyzer see dynamically loaded stylesheets?

No. It reads only the files you give it. When it suspects missing input, it reports the analysis as incomplete.

Do custom bundles work with a strict CSP?

Yes, like the full bundle. Serve the file from your own origin.

Full, compact or custom?

Full when you are not sure what your stylesheets use. Compact is the same full runtime with a shorter describe() registry; it is not a feature selection. Custom when you know, and the analysis is complete.

Can I load a custom bundle from a CDN?

No. Only the full and compact bundles will be published. A custom bundle is a file you host.