React with Vite

Set up

1. Write the configuration once

   A partial that forwards @nuvoui/core/mixins with your settings. The mixins entry has the same API as @nuvoui/core (apply(), every mixin, token(), with()) and outputs no CSS.

   src/styles/_nuvo.scss

   @forward "@nuvoui/core/mixins" with ($brand: #4361ee, $generate-utility-classes: true);

2. Create the global stylesheet

   It emits the tokens, the reset, the base styles and the utility classes with your configuration. @use "nuvo" comes first, so core loads with the configured brand. Nothing else in the app loads @nuvoui/core.

   src/styles/global.scss

   @use "nuvo";
   @use "@nuvoui/core";

3. Import it in the entry

   Imported once in main.tsx, it applies to every page of the app.

   src/main.tsx

   import { StrictMode } from 'react'
   import { createRoot } from 'react-dom/client'
   import './styles/global.scss'
   import App from './App.tsx'
   
   createRoot(document.getElementById('root')!).render(
     <StrictMode>
       <App />
     </StrictMode>,
   )

With utility classes

Classes go straight into className.

import Card from './components/Card'

export default function App() {
  return (
    <main className="grid gap-4 p-6">
      <div className="flex between x-center gap-3 p-4 bg-surface border rounded-md">
        <span className="font-semibold">Invoices</span>
        <span className="bg-success-subtle text-success text-xs rounded-full px-2 py-1">Paid</span>
      </div>
      <Card title="Quarterly report">Revenue and churn for July to September.</Card>
    </main>
  )
}

With apply()

Each component loads the partial and writes only its own rules. Numbers are configuration keys (p(4) is var(--nu-space-4)), and modifiers come after the utility: state and breakpoint in either order.

@use "../styles/nuvo" as *;

.card {
    @include apply(p(4), bg(surface), rounded(md), shadow(md) hover, p(6) md);
}

.title {
    @include apply(m(0), font-size(lg), font(semibold));
}

.text {
    @include apply(mt(2), mb(0), text-color(muted));
}

import type { ReactNode } from 'react'
import styles from './Card.module.scss'

export default function Card({ title, children }: { title: string; children: ReactNode }) {
  return (
    <article className={styles.card}>
      <h2 className={styles.title}>{title}</h2>
      <p className={styles.text}>{children}</p>
    </article>
  )
}

Prebuilt CSS

To use the default configuration with no Sass step, import the prebuilt stylesheet in place of global.scss. Use the @nuvoui/core/min.css specifier: Vite types declare imports ending in .css, and tsc rejects @nuvoui/core/css with error TS2882.

import '@nuvoui/core/min.css'

Dark mode

With no data-theme on <html>, the tokens follow the operating system setting. Set data-theme="dark" or data-theme="light" to choose one, and change it from a script to switch at runtime: document.documentElement.dataset.theme = "dark". Any element can carry data-theme to theme only its own subtree. Every class and every apply() rule reads the tokens, so nothing else changes.

<html lang="en" data-theme="dark">

What gets emitted

The global stylesheet holds the tokens, the light and dark themes, the reset, the base styles, the tooltips, the @property registrations and, with $generate-utility-classes: true, every utility class: about 1 MB minified, 92 KB gzipped. Without the classes it is about 42 KB. Load it on every page, because the tokens live there.

Card.module.scss compiles to five rules and nothing else: the hashed .card class, its hover, its md padding, the title and the text. The tokens are not repeated per component, and a component cannot reset the configured brand.