NibCSS

@nibcss/unplugin

One plugin for Vite, webpack, Rspack, Rollup and esbuild: every option, what it generates and how the dev server behaves.

2 min readv1

Entry points#

TypeScript
import nib from "@nibcss/unplugin/vite";
import nib from "@nibcss/unplugin/webpack";
import nib from "@nibcss/unplugin/rspack";
import nib from "@nibcss/unplugin/rollup";
import nib from "@nibcss/unplugin/esbuild";

Options#

Option

Default

What it does

rewrite

"keep" in dev, true in a build

compile static attributes into classes. true replaces the attribute; "keep" adds the class and leaves it; false leaves the markup alone

runtime

true

webpack/Rspack: append the runtime to the client entry

devtools

true

mount the diagnostics overlay in dev (needs debug: true)

config

auto-detected

path to the config file

include / exclude

project sources

extra globs to scan, or skip

override

—

config fields that win over the file

scaffold

true

false stops the plugin creating the config file

client

auto-detected

tell the plugin which compiler is the browser bundle

rewrite, in full#

Value

Markup after the build

Who applies the class

true

<div class="nib-a1b2">

nobody — it is already there

"keep"

<div class="nib-a1b2" nib="p=16px">

nobody, but the runtime can re-resolve it when the config changes

false

<div nib="p=16px">

the runtime, in the browser

"keep" is the dev default because it is what makes a config edit apply to the page you already have open.

What it generates#

Path

What it is

node_modules/.nib/styles.css

the stylesheet, served as @nibcss/styles.css

node_modules/.nib/config.mjs, config.json

the resolved config, as a module and as data

node_modules/@nibcss/config

a real package re-exporting it, so the import type-checks with no paths entry

node_modules/.nib/boot.mjs

webpack/Rspack: the runtime entry appended to the client bundle

node_modules/.nib/dev.mjs

dev only, debug: true: the overlay and the current warnings

Every generated file opens with /* eslint-disable */ and an @generated marker, and everything lives inside node_modules — nothing to add to .gitignore.

Dev-server behaviour#

  • A config edit is applied to the open page — the build pushes the new config and the new stylesheet over the dev channel, the page swaps the stylesheet and re-resolves its elements, and rules the change removed go away too.
  • A source edit is a normal hot update.
  • Diagnostics are served at /__nib/warnings and pushed to the overlay as you type.

Next steps#