@kbach/react 1.0.0-beta.4 → 1.0.0-beta.6

package/README.md

@@ -32,14 +32,11 @@ export default defineConfig({
 
 ```tsx
 // main.tsx
-import { initKbach } from '@kbach/react';
 import { createRoot } from 'react-dom/client';
 import App from './App';
 import './kbach.css';
 
-initKbach().then(() => {
-  createRoot(document.getElementById('root')!).render(<App />);
-});
+createRoot(document.getElementById('root')!).render(<App />);
 ```
 
 ```tsx
@@ -48,6 +45,101 @@ initKbach().then(() => {
 </div>
 ```
 
+That's the whole setup — the Vite plugin config plus a `kbach.css` with the
+two marker comments. No `initKbach()`/async step before your first render:
+`className` here is a plain string prop, resolved entirely by the CSS
+`@kbach/react/vite` already generated at build time, same as any other
+static stylesheet — nothing here calls into the WASM engine at render time,
+so there's nothing to await.
+
+`initKbach()` (still exported from `@kbach/react`) is only needed for two
+opt-in features that genuinely do call into the Rust/WASM engine at
+runtime: the dynamic [`kb()`](#dynamic-classes) function, and the optional
+`@kbach/react/jsx-runtime` (a `jsxImportSource` override that intercepts
+*every* element's `className` automatically instead of relying on the
+static build). If you use either, `await initKbach()` once before your
+first render, same as before.
+
+## React Router
+
+Nothing beyond the Quick Start above — React Router is a client-side
+routing library with no build-tool coupling of its own, so it layers on
+top of the exact same Vite + `kbach.css` setup with zero extra
+configuration, whether you're on the framework mode (`createBrowserRouter`)
+or the classic `<BrowserRouter>` component form:
+
+```tsx
+// main.tsx
+import { createRoot } from 'react-dom/client';
+import { RouterProvider, createBrowserRouter } from 'react-router';
+import './kbach.css';
+import Home from './routes/home';
+import About from './routes/about';
+
+const router = createBrowserRouter([
+  { path: '/', Component: Home },
+  { path: '/about', Component: About },
+]);
+
+createRoot(document.getElementById('root')!).render(<RouterProvider router={router} />);
+```
+
+Every route's own components use `className` exactly like any other
+component — routing has no effect on how Kbach resolves classes, since
+resolution already happened at build time, before routing even enters the
+picture.
+
+## Next.js
+
+Next.js uses webpack/Turbopack, not Vite, so `@kbach/react/vite` doesn't
+apply — use `@kbach/react/postcss` instead, which does the exact same
+build-time class-string scanning and CSS generation (they share the same
+underlying engine), just wired into PostCSS, which both of Next.js's
+bundlers already run for you with zero extra config.
+
+```js
+// postcss.config.js
+module.exports = {
+  plugins: {
+    '@kbach/react/postcss': {},
+  },
+};
+```
+
+```css
+/* app/globals.css (App Router) or styles/globals.css (Pages Router) */
+/* kbach:start */
+/* kbach:end */
+```
+
+```tsx
+// app/layout.tsx
+import './globals.css';
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en">
+      <body>{children}</body>
+    </html>
+  );
+}
+```
+
+Plain `className="..."` strings on Server Components work with zero extra
+setup — the CSS already exists at build time, same as any other static
+stylesheet. Hook-based exports (`useTheme`, `useColors`, `<ThemeProvider>`)
+already carry their own `'use client'` directive, so importing them into a
+Client Component just works; importing one into a Server Component is a
+compile-time error the same way importing `useState` into one would be —
+that's React's own rule, not a Kbach limitation.
+
+`root`/`theme`/`config`/`include`/`safelist` options all match
+`@kbach/react/vite`'s exactly (see `KbachPluginOptions`, above) — `root`
+additionally defaults to `process.cwd()` rather than a bundler-resolved
+project root, since PostCSS has no equivalent to Vite's own resolved
+`root` to read; pass it explicitly if your `postcss.config.js` doesn't
+live at your project root (e.g. a monorepo app).
+
 ## Dark mode
 
 ```tsx
@@ -77,16 +169,20 @@ setTheme({
 ## Dynamic classes
 
 Classes that appear literally in your source are resolved at build time.
-For classes assembled from truly dynamic data, use `kb()`:
+For classes assembled from truly dynamic data, use `kb()` — this is the
+one thing in this package that genuinely calls into the WASM engine at
+runtime, so `await initKbach()` once at startup before the first `kb()`
+call (or before rendering, if you can't guarantee it runs first otherwise):
 
 ```ts
-import { kb } from '@kbach/react';
+import { initKbach, kb } from '@kbach/react';
 
+await initKbach();
 const className = kb(`bg-${userColor}-6`);
 ```
 
 Prefer a `safelist` entry in the plugin config when the possible values are
-known ahead of time — keeps everything static.
+known ahead of time — keeps everything static, no `initKbach()` needed.
 
 ## Reading colors as values