NibCSS

Build time vs runtime

What the build plugin does, what the runtime does, and how they work together.

1 min readv1

NibCSS runs the same engine in two places. Knowing which one handles an attribute tells you what it costs.

Build time — @nibcss/unplugin, @nibcss/next, @nibcss/nuxt, the CLI#

The plugin scans your source files for string-literal nib attributes and writes their CSS into node_modules/.nib/styles.css, which you import once as @nibcss/styles.css.

  • The browser loads it as a normal render-blocking stylesheet → styled first paint.
  • HMR in development; the dev overlay reports mistakes with file and line.

rewrite: true#

Also replaces each static nib="…" with the class names at build time:

Text
in:   <div nib="p=16px; bdrd=8px">
out:  <div class="nib-jbmcpl nib-1x0…">

Rewritten elements need no JavaScript at all. Attributes that are expressions (nib={x}, interpolated strings, Vue :nib) are left for the runtime.

Runtime — @nibcss/runtime and the adapters#

In the browser the runtime scans [nib] and [data-nib], generates CSS into one <style>, and keeps watching the DOM, so elements added or changed later are styled. The adapters (useNib, v-nib, use:nib, [nib]) generate classes synchronously during render.

Who handles what#

Attribute

Build

Runtime

<div nib="p=16px">

✅

✅ (if not rewritten)

nib={expression} in JSX

—

✅

useNib(…) with a changing value

—

✅

HTML from a CMS / innerHTML

—

✅

Project

Setup

Static site, marketing pages

plugin + rewrite: true, no runtime

SPA with some dynamic styles

plugin + runtime/adapter

Server templates

CLI; add the runtime only for client-side markup

Prototype

CDN runtime only

Next steps#