NibCSS

@nibcss/core

The engine: parse attributes, resolve tokens and recipes, generate CSS. Zero dependencies, no DOM, fully deterministic.

2 min readv1

@nibcss/core is the part that turns "p=16px; hover:bgc=#333" into CSS. It has no dependencies and never touches the DOM, which is why the same engine runs inside the bundler plugin, the CLI, the browser runtime and your own scripts — and why a class name is identical in all four.

You rarely install it directly: every other package depends on it. Reach for it when you are building a tool of your own.

Install#

Terminal
npm i @nibcss/core

The engine#

TypeScript
import { createEngine } from "@nibcss/core";

const engine = createEngine(config);
const { classNames, rules, warnings, diagnostics } = engine.process("p=16px; hover:bgc=#333");

Member

What it does

process(attr)

{ classNames, rules, warnings, diagnostics } for one attribute string

css()

every rule produced so far, as a stylesheet

update(config)

replace the config and clear the caches

stats()

rule and class counts

config

the resolved config, every optional field filled in

Everything is synchronous and deterministic: a class name is a hash of the rule it carries, so the same declaration always produces the same name — on every machine, in every build, in the browser and on the server.

Every export#

Export

What it is

defineConfig(config)

identity, for editor completion in your config file

resolveConfig(config)

fill in every default

mergeConfig(base, over)

merge two configs one level deep — a token group adds to the palette instead of replacing it

parseAttribute, parseToken, splitTokens

the parser

resolveTokens

$group.key → value

SHORTCUTS, CSS_PROPERTIES, looksLikeCssProperty

the shorthand table and the property list

DEFAULT_BREAKPOINTS, mediaQuery

breakpoints

PSEUDO_CLASSES, PSEUDO_ELEMENTS, isPseudo, pseudoSelector

variants

createValidator, KEYWORD_VALUES, isKnownBadKeyword, acceptedValues

value checking

DEFAULT_PREFLIGHT, preflightCss

the reset

createReporter, CATALOGS, BUILT_IN_LANGUAGES, resolveCatalog, interpolate

diagnostics and their translations

closest, didYouMean, distance

the "did you mean" suggestions

hash

the class-name hash (FNV-1a, base36)

CONFIG_TEMPLATE

the commented config file the tools scaffold

Two fields that exist only for embedding#

Field

What it is

onWarn(message, context?)

where diagnostics go; defaults to console.warn when debug is on

supports(property, value)

a value checker. The browser runtime passes CSS.supports; without it the engine falls back to its keyword tables

A build script of your own#

TypeScript
import { readFileSync, writeFileSync, globSync } from "node:fs";
import { createEngine } from "@nibcss/core";
import config from "./nibcss.config.ts";

const engine = createEngine({ ...config, debug: true, onWarn: (m) => console.warn(m) });

const ATTR = /\bnib\s*=\s*"([^"]*)"/g;
for (const file of globSync("src/**/*.html")) {
  const source = readFileSync(file, "utf8");
  for (const [, attr] of source.matchAll(ATTR)) engine.process(attr);
}

writeFileSync("dist/nib.css", engine.css());
console.log(engine.stats());   // { rules: 318, classes: 318 }

Next steps#