Installation

Install the release candidate

The 0.1.0 release candidate is not yet published on npm. Pack it from the repository, then install the archive in an existing React app. Workspace apps can use workspace:* instead.

React and ReactDOM must satisfy ^19.2.8. Import @mizen-labs/ui/styles.css once at the application root. It contains the compiled atomic styles; components load their own structural CSS. No consumer Babel or PostCSS setup is required.

pnpm --filter @mizen-labs/ui pack --out /tmp/mizen-ui.tgz
# In your consumer app:
npm install /tmp/mizen-ui.tgz

• CLI setup and diagnostics

Next

Transpile the package: its components import their own CSS files. Then render ThemeScript and ThemeProvider in the root layout.

export default { transpilePackages: ["@mizen-labs/ui"] };

• Theme and font layout

Global stylesheet

Import @mizen-labs/ui/styles.css before your app stylesheet in the root layout. The theming guide shows the complete Next layout; the root route below shows TanStack Start.

Your app owns its document defaults. Set your interface font on body; Mizen controls inherit it.

body {
  margin: 0;
  font-family: system-ui, sans-serif;
}

*, *::before, *::after {
  box-sizing: border-box;
}

React + Vite

The default create-vite React template works without special Vite configuration. Import Mizen CSS in src/main.tsx or src/main.jsx, call initializeTheme before createRoot, and wrap the mounted tree in ThemeProvider. Keep existing StrictMode, application providers, and CSS.

JavaScript omits the TypeScript non-null assertion after getElementById. Initialization applies the saved or system theme before the first app frame. Custom initialization and provider options must match. This client-only setup needs no SSR ThemeScript or ssr.noExternal setting. Init and doctor support conventional index.html module entries.

import "@mizen-labs/ui/styles.css";
import { ThemeProvider } from "@mizen-labs/ui/theme";
import { initializeTheme } from "@mizen-labs/ui/theme/initialize";
import { StrictMode } from "react";
import { createRoot } from "react-dom/client";
import App from "./App";
import "./index.css";

initializeTheme();
createRoot(document.getElementById("root")!).render(
  <ThemeProvider><StrictMode><App /></StrictMode></ThemeProvider>
);

TanStack Start: Vite

TanStack Start builds with Vite. The package ships its atomic CSS, so no StyleX compiler plugin is needed in the consumer.

Keep @mizen-labs/ui out of the server's externals. Its components import their own CSS files, which Node cannot load directly.

import { tanstackStart } from "@tanstack/react-start/plugin/vite";
import viteReact from "@vitejs/plugin-react";
import { defineConfig } from "vite";

export default defineConfig({
  // Mizen imports its own CSS files, so the server bundle must include it.
  ssr: { noExternal: ["@mizen-labs/ui"] },
  plugins: [tanstackStart(), viteReact()],
});

TanStack Start: root route

Render ThemeScript in the head, before HeadContent, so the theme applies before first paint. Load the package stylesheet and font through the route's head links, and wrap the content in ThemeProvider.

A packed-archive test builds this setup and checks server rendering, hydration, the theme bootstrap, extracted styles, and keyboard interaction, alongside the Next consumer.

import mizenCss from "@mizen-labs/ui/styles.css?url";
import fontCss from "@fontsource-variable/wix-madefor-text/wght.css?url";
import { ThemeProvider, ThemeScript } from "@mizen-labs/ui/theme";
import { createRootRoute, HeadContent, Scripts } from "@tanstack/react-router";
import appCss from "../styles.css?url";

export const Route = createRootRoute({
  head: () => ({
    links: [
      { href: mizenCss, rel: "stylesheet" },
      { href: fontCss, rel: "stylesheet" },
      { href: appCss, rel: "stylesheet" },
    ],
  }),
  shellComponent: RootDocument,
});

function RootDocument({ children }) {
  return (
    <html lang="en" suppressHydrationWarning>
      <head>
        <ThemeScript />
        <HeadContent />
      </head>
      <body>
        <ThemeProvider>{children}</ThemeProvider>
        <Scripts />
      </body>
    </html>
  );
}

Tested versions

Tested together: React 19.3, StyleX 0.19.1, Next 16.3, and TanStack Start 1.169 with Vite 8. A packed-archive test installs Mizen into a fresh app for each framework and checks server rendering, hydration, the theme bootstrap, extracted styles, and keyboard interaction.

Mizen is pre-1.0: minor versions can change the API.