NibCSS

The config file

Where the config lives, how every tool finds it, and how one file feeds the build, the CLI and the runtime.

1 min readv1

One file, three consumers#

nibcss.config.ts at the project root is read by:

  1. the build plugin (@nibcss/unplugin, @nibcss/next, @nibcss/nuxt),
  2. the CLI (@nibcss/cli),
  3. the runtime, through the generated @nibcss/config module.

Tokens, recipes and diagnostics therefore behave identically at build time and in the browser.

File names#

Searched in this order at the project root: nibcss.config.ts → .mts → .js → .mjs → .cjs → the same with nib.config. Point elsewhere with the plugin's config option or the CLI's --config flag.

Shape#

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

export default defineConfig({
  darkMode: "class",
  debug: true,
  tokens: { color: { brand: "#4F52D9" } },
  components: { btn: "p=8px 16px; bdrd=8px" },
});

defineConfig only adds types — it returns the object unchanged.

Sharing the config with the runtime#

TSX
import config from "@nibcss/config";
<NibProvider {...config}>…</NibProvider>

When changes apply#

Tool

Picks up config edits

Vite plugin

immediately, with HMR

nib watch

on the next rebuild

webpack / Next.js

normally on the next compile — if a new recipe is still reported as unknown, restart the dev server

CDN runtime

on reload, or live with Nib.configure()

Missing or empty config#

Two situations are always reported, even without debug: no config file at all, and a config that exports nothing (commented out, or missing export default). Everything else still works without a config.

Next steps#