NibCSS

Configuration options

Every option in nibcss.config.ts — what it does, its default and an example.

2 min readv1

Option

Default

Summary

prefix

"nib-"

start of every generated class name

pseudos

true

allow hover:, before: … modifiers

darkMode

"class"

how dark: rules are scoped

breakpoints

8 built-ins

responsive modifiers

tokens

{}

named values, referenced as $group.key

components

{}

recipes

shortcuts

{}

extra shorthand → property names

strict

false

drop invalid values and unknown modifiers

preflight

true

base reset in @layer nib-preflight

debug

false

report diagnostics

language

"uz"

language of diagnostics

messages

{}

re-word diagnostics or add a language

supports

runtime: CSS.supports

value validator

onWarn

console.warn when debug

diagnostic sink

prefix#

TypeScript
prefix: "ui-",   // → .ui-jbmcpl

Useful when two NibCSS builds share a page (a widget embedded in a host app).

pseudos#

false rejects every pseudo modifier with a "pseudo variants are disabled" warning.

darkMode#

TypeScript
darkMode: "class",  // .dark .nib-x { … } — toggle with runtime.toggleDarkMode()
darkMode: "media",  // @media (prefers-color-scheme: dark) { … }
darkMode: false,    // every dark: rule is dropped

breakpoints#

Merged over the built-ins (xs 480, sm 576, md 768, lg 992, xl 1024, 2xl 1200, 3xl 1440, 4xl 1536).

TypeScript
breakpoints: {
  md: { min: 800 },
  tablet: { min: 768, max: 1023 },
  wide: { min: 1800 },
},

tokens#

TypeScript
tokens: {
  color: { brand: "#4F52D9", "brand-hover": "#3A3DBF" },
  space: { sm: "8px", md: "16px" },
},

components#

TypeScript
components: {
  btn: "d=inline-flex; p=8px $space.md; bdrd=8px",
  "btn-primary": "btn; bgc=$color.brand; cl=#fff",
},

shortcuts#

TypeScript
shortcuts: {
  size: "width height",
  tap: "-webkit-tap-highlight-color",
},

strict#

Problem

strict: false (default)

strict: true

unknown shorthand

warning, no CSS

warning, no CSS

invalid value (opc=red)

warning, emitted

warning, dropped

unknown modifier (xz:)

warning, emitted as a pseudo

warning, dropped

unknown token

warning, left in the value

warning, left in the value

preflight#

TypeScript
preflight: true,     // the built-in reset (default)
preflight: false,    // no reset
preflight: "*, *::before, *::after { box-sizing: border-box }",   // your own

debug#

Turns on diagnostics: the terminal (with file and line at build time), nib:warning events in the browser and the dev overlay. Toggling it takes effect without restarting.

language#

Built in: uz (default), en, ru, tr, es, de, zh.

messages#

Re-word a line or add a language; a missing key falls back to English:

TypeScript
language: "fr",
messages: {
  fr: {
    "invalid-value": "« {value} » n'est pas valide pour {property}",
    "unknown-utility": "Utilitaire inconnu « {name} »",
  },
},

supports#

A (property, value) => boolean validator. The runtime injects CSS.supports; builds use the engine's keyword tables. Override only for custom environments.

onWarn#

Receives (message, context, diagnostic) — the third argument is structured (id, parameters, suggestions):

TypeScript
onWarn: (message, context, diagnostic) => {
  telemetry.track("nib_warning", { id: diagnostic?.id, context });
},

Plugin-only options#

These belong to the build plugin, not the config file: rewrite, include, exclude, devtools, scaffold, config, override. See unplugin API.

Next steps#