NibCSS

Troubleshooting

Fixes for styles that do not apply, stale recipes, hydration warnings and dark-mode problems.

1 min readv1

Styles do not apply at all#

  1. Is the stylesheet imported? import "@nibcss/styles.css" once in the entry file.
  2. Is the plugin running? Next 16 uses Turbopack by default — add --webpack.
  3. Is it a real attribute? nib="…", not nib:"…" or class="…".
  4. Any warnings? Set debug: true and read the terminal / overlay.

A new recipe or token is "unknown"#

The config is read when the dev server starts. Vite picks up changes immediately; with webpack/Next.js, restart the dev server once after adding recipes. Also check that the config has export default.

A recipe used as a class does nothing#

className="btn" bypasses the engine. Use nib="btn" or useNib("btn").

Flash of unstyled content#

  • CDN: the script must be in <head>, without defer, async or type="module".
  • Bundler: import the stylesheet; consider rewrite: true.
  • SSR with dynamic values: render <NibStyles />.

"Invalid DOM property class" (React)#

An element has both nib="…" and a dynamic className={…} while rewrite is on. Move the dynamic class to a wrapper or use useNib for the whole element.

Hydration mismatch on <html>#

The runtime adds class="dark" before React hydrates. Add suppressHydrationWarning to <html>.

Dark mode does not switch#

  • darkMode must be "class" for a toggle; "media" follows the OS only.
  • Something else may be removing dark from <html> — check other theme scripts.
  • The saved preference lives in localStorage["nib-dark"]; delete it to fall back to the OS.

The stylesheet keeps growing#

A value is interpolated too freely (every pixel, every frame). Use CSS variables for continuous values and leave gc on.

A property is reported as unknown#

Not every CSS property is known to the engine yet (for example fill and stroke). Use a CSS variable or an attribute, and report it on GitHub.

Next steps#