@kbach/react 1.0.0-beta.7 → 1.0.0-beta.8

package/README.md

@@ -24,11 +24,10 @@ export default defineConfig({
 });
 ```
 
-```css
-/* src/kbach.css */
-/* kbach:start */
-/* kbach:end */
-```
+That's it — the plugin finds or creates your `kbach.css` on its own,
+wherever your source actually lives (`src/`, `app/`, ...; see "Where does
+`kbach.css` go?" below if you want to know exactly where or control it).
+Import it once from your entry point and render normally:
 
 ```tsx
 // main.tsx
@@ -45,12 +44,25 @@ createRoot(document.getElementById('root')!).render(<App />);
 </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.
+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.
+
+### Where does `kbach.css` go?
+
+You don't need to think about this for the common case — skip to
+[React Router](#react-router)/[Next.js](#nextjs) if that's what brought you
+here. For everyone else: the plugin looks for a file already containing
+`/* kbach:start */`/`/* kbach:end */` markers under each of your `include`
+directories (`src`, `app`, `pages`, `components` by default) and the
+project root, in that order, and keeps using whichever one it finds. If
+none exists yet, it creates `<first-existing-include-dir>/kbach.css` for
+you, markers included — you never have to hand-author that file. Pass
+`cssFile` to `kbach()` only if you want to pin the location explicitly
+(a path outside every `include` dir, or more than one candidate present at
+once).
 
 `initKbach()` (still exported from `@kbach/react`) is only needed for two
 opt-in features that genuinely do call into the Rust/WASM engine at
@@ -88,34 +100,35 @@ createRoot(document.getElementById('root')!).render(<RouterProvider router={rout
 ```
 
 **Framework mode** (`npx create-react-router@latest` — file-based routing
-under `app/`, its own Vite plugin, SSR by default): two things differ from
-the Quick Start, both because this mode owns your project's structure and
-render lifecycle, not you:
-
-1. Its convention is `app/`, not `src/` — pass `cssFile` so the plugin
-   writes to `app/kbach.css` instead of the (here, nonexistent) default:
-   ```ts
-   // vite.config.ts
-   import { reactRouter } from '@react-router/dev/vite';
-   import { kbach } from '@kbach/react/vite';
-   import { defineConfig } from 'vite';
-
-   export default defineConfig({
-     plugins: [kbach({ cssFile: 'app/kbach.css' }), reactRouter()],
-   });
-   ```
-2. **Don't call `createRoot` yourself in `app/root.tsx`** — the framework's
-   own generated client/server entry points already do this; `root.tsx`
-   only ever *exports* a `Layout`/default component. Adding your own
-   `createRoot(...).render(...)` at that file's top level runs during SSR
-   too, where `document` doesn't exist, and crashes the build immediately.
-   `app/root.tsx` needs only:
-   ```tsx
-   import './kbach.css';
-   export default function App() {
-     return <Outlet />;
-   }
-   ```
+under `app/`, its own Vite plugin, SSR by default):
+
+```ts
+// vite.config.ts
+import { reactRouter } from '@react-router/dev/vite';
+import { kbach } from '@kbach/react/vite';
+import { defineConfig } from 'vite';
+
+export default defineConfig({
+  plugins: [kbach(), reactRouter()],
+});
+```
+
+Same `kbach()` call as everywhere else — its `app/`-vs-`src/` convention
+is exactly what auto-detection (above) exists for, so there's nothing
+React-Router-specific to configure. The one real gotcha is unrelated to
+Kbach at all: **don't call `createRoot` yourself in `app/root.tsx`** — the
+framework's own generated client/server entry points already do this;
+`root.tsx` only ever *exports* a `Layout`/default component. Adding your
+own `createRoot(...).render(...)` at that file's top level runs during SSR
+too, where `document` doesn't exist, and crashes the build immediately.
+`app/root.tsx` needs only:
+
+```tsx
+import './kbach.css';
+export default function App() {
+  return <Outlet />;
+}
+```
 
 Either mode: every route's own components use `className` exactly like any
 other component — routing has no effect on how Kbach resolves classes,

package/dist/{chunk-P4CQSYIL.mjs → chunk-3E26VMLA.mjs}

@@ -7,7 +7,7 @@ import {
 } from "./chunk-N5HCQIBB.mjs";
 
 // src/vite-plugin/index.ts
-import { writeFileSync, mkdirSync, existsSync } from "fs";
+import { readFileSync as readFileSync3, writeFileSync, mkdirSync, existsSync, statSync as statSync2 } from "fs";
 import { join as join4, dirname } from "path";
 import { createRequire } from "module";
 
@@ -1235,6 +1235,27 @@ function readSourceFile(path) {
 }
 
 // src/vite-plugin/index.ts
+function findMainCSSFile(root, includeDirs, explicitCssFile) {
+  if (explicitCssFile) return join4(root, explicitCssFile);
+  const searchDirs = [...includeDirs, "."];
+  for (const dir of searchDirs) {
+    const candidate = join4(root, dir, "kbach.css");
+    if (!existsSync(candidate)) continue;
+    try {
+      const content = readFileSync3(candidate, "utf-8");
+      if (content.includes(KBACH_START) && content.includes(KBACH_END)) return candidate;
+    } catch {
+    }
+  }
+  for (const dir of includeDirs) {
+    const full = join4(root, dir);
+    try {
+      if (statSync2(full).isDirectory()) return join4(full, "kbach.css");
+    } catch {
+    }
+  }
+  return join4(root, includeDirs[0] ?? "src", "kbach.css");
+}
 var DEFAULT_SCAN_DIRS = ["src", "app", "pages", "components"];
 var CSS_SYNC_DEBOUNCE_MS = 50;
 function writeFileEnsuringDir(path, content) {
@@ -1259,8 +1280,9 @@ function kbach(options = {}) {
   let root = process.cwd();
   let theme = defaultTheme;
   let engine = createKbachStaticCssEngine({ root, theme, themeJson: JSON.stringify(theme), includeDirs, safelist });
+  let mainCSSFilePath = join4(root, "src", "kbach.css");
   function mainCSSFile() {
-    return join4(root, options.cssFile ?? "src/kbach.css");
+    return mainCSSFilePath;
   }
   function classNameHintsFile() {
     return join4(root, ".kbach", "kbach-classnames.d.ts");
@@ -1270,7 +1292,7 @@ function kbach(options = {}) {
     writeFileEnsuringDir(classNameHintsFile(), dts);
   }
   function syncMainCSSFile(server) {
-    const changed = writeKbachToFile(mainCSSFile(), engine.generateCSS(), readSourceFile, (p, c) => writeFileSync(p, c, "utf-8"));
+    const changed = writeKbachToFile(mainCSSFile(), engine.generateCSS(), readSourceFile, writeFileEnsuringDir);
     if (changed && server) server.watcher.emit("change", mainCSSFile());
   }
   let syncTimer = null;
@@ -1288,12 +1310,13 @@ function kbach(options = {}) {
       root = resolved.root;
       theme = resolveEffectiveTheme(root, options);
       engine = createKbachStaticCssEngine({ root, theme, themeJson: JSON.stringify(theme), includeDirs, safelist });
+      mainCSSFilePath = findMainCSSFile(root, includeDirs, options.cssFile);
     },
     buildStart() {
       engine.scanProjectCssSelectorsOnce();
       engine.initialScan();
       engine.processSafelist();
-      writeKbachToFile(mainCSSFile(), engine.generateCSS(), readSourceFile, (p, c) => writeFileSync(p, c, "utf-8"));
+      writeKbachToFile(mainCSSFile(), engine.generateCSS(), readSourceFile, writeFileEnsuringDir);
       writeClassNameHints();
     },
     // handleHotUpdate covers edits; add/unlink (create/delete) land on the
@@ -1332,6 +1355,7 @@ function kbach(options = {}) {
 
 export {
   createKbachStaticCssEngine,
+  findMainCSSFile,
   DEFAULT_SCAN_DIRS,
   CSS_SYNC_DEBOUNCE_MS,
   loadConfigFile,

package/dist/postcss-plugin.mjs

@@ -2,7 +2,7 @@ import {
   DEFAULT_SCAN_DIRS,
   createKbachStaticCssEngine,
   resolveEffectiveTheme
-} from "./chunk-P4CQSYIL.mjs";
+} from "./chunk-3E26VMLA.mjs";
 import "./chunk-NKR3PSWO.mjs";
 import "./chunk-N5HCQIBB.mjs";
 

package/dist/vite-plugin.d.mts

@@ -29,16 +29,39 @@ interface KbachPluginOptions {
     safelist?: string[];
     /**
      * Path to the `kbach:start`/`kbach:end` marker file, relative to Vite's
-     * resolved root. Defaults to `"src/kbach.css"` — override this for any
-     * project whose source root isn't `src/`: React Router v7's framework
-     * mode (`app/kbach.css`), a Pages-Router-style Next.js app using this
-     * plugin directly (`styles/kbach.css`), or any other convention. Getting
-     * this wrong fails loudly at build start (`ENOENT` writing the file's
-     * parent directory) rather than silently generating nothing, but it's
-     * still worth setting explicitly if your project doesn't use `src/`.
+     * resolved root. Not needed for the common case — `kbach()` auto-detects
+     * it (see `findMainCSSFile`'s own doc comment) by finding wherever you
+     * actually put the two marker comments, regardless of whether your
+     * project's source root is `src/`, `app/` (React Router v7's framework
+     * mode), or anything else in `include`. Set this explicitly only to
+     * disambiguate a genuinely unusual layout (a marker file outside every
+     * `include` directory, or more than one candidate present at once).
      */
     cssFile?: string;
 }
+/**
+ * Finds where to read/write the `kbach:start`/`kbach:end` marker file,
+ * with no configuration required for the common case:
+ *
+ * 1. An explicit `cssFile` always wins (the one supported escape hatch).
+ * 2. Otherwise, look for a `kbach.css` already containing BOTH markers in
+ *    each `include` directory (in order) and the project root itself —
+ *    wherever you actually created it is where this plugin keeps using it,
+ *    regardless of which framework convention (`src/`, `app/`, ...) that
+ *    is. This is what makes React Router v7's framework mode (`app/
+ *    kbach.css`) and a plain Vite app (`src/kbach.css`) both "just work"
+ *    with the exact same `kbach()` call — no per-framework option needed.
+ * 3. No marked file exists yet (first run in a fresh project) — pick the
+ *    first `include` directory that already exists as a real directory on
+ *    disk, so the file this plugin is about to CREATE lands somewhere that
+ *    won't need its own parent directory made up out of nothing.
+ * 4. Nothing in `include` exists yet either (a genuinely empty project,
+ *    scaffolded before its first source file) — fall back to the first
+ *    configured `include` entry regardless; `writeMainCSSFile` (below)
+ *    creates its parent directory unconditionally, so this never crashes
+ *    even here.
+ */
+declare function findMainCSSFile(root: string, includeDirs: string[], explicitCssFile?: string): string;
 declare const DEFAULT_SCAN_DIRS: string[];
 declare const CSS_SYNC_DEBOUNCE_MS = 50;
 /**
@@ -73,11 +96,12 @@ declare function resolveEffectiveTheme(root: string, options: {
  * Build-time static CSS generation for Vite — scans source files for
  * Kbach class strings, resolves them through the same Rust engine the
  * runtime uses (via the Node-target WASM build, see wasmNode.ts), and
- * writes a real kbach.css. Simplified vs old-kbach's version: expects a
- * marker file to already exist at a fixed conventional path — `src/
- * kbach.css` by default, override via `cssFile` for any other source root
- * (create it with `/* kbach:start *\/` / `/* kbach:end *\/` markers)
- * rather than scanning the whole project for a file named kbach.css.
+ * writes a real kbach.css. Auto-detects WHERE that file is (or should be
+ * created) via `findMainCSSFile` — no per-framework config needed for
+ * `src/`, `app/` (React Router v7's framework mode), or any other
+ * `include` convention; create a file with `/* kbach:start *\/` / `/*
+ * kbach:end *\/` markers wherever your project's source actually lives
+ * and this plugin finds it there.
  *
  * The actual scanning/resolution/generation logic lives in
  * `staticCss/engine.ts`, shared with `postcss-plugin/index.ts` (Next.js/
@@ -87,4 +111,4 @@ declare function resolveEffectiveTheme(root: string, options: {
  */
 declare function kbach(options?: KbachPluginOptions): Plugin;
 
-export { CSS_SYNC_DEBOUNCE_MS, DEFAULT_SCAN_DIRS, type KbachPluginOptions, kbach, loadConfigFile, resolveEffectiveTheme };
+export { CSS_SYNC_DEBOUNCE_MS, DEFAULT_SCAN_DIRS, type KbachPluginOptions, findMainCSSFile, kbach, loadConfigFile, resolveEffectiveTheme };

package/dist/vite-plugin.d.ts

@@ -29,16 +29,39 @@ interface KbachPluginOptions {
     safelist?: string[];
     /**
      * Path to the `kbach:start`/`kbach:end` marker file, relative to Vite's
-     * resolved root. Defaults to `"src/kbach.css"` — override this for any
-     * project whose source root isn't `src/`: React Router v7's framework
-     * mode (`app/kbach.css`), a Pages-Router-style Next.js app using this
-     * plugin directly (`styles/kbach.css`), or any other convention. Getting
-     * this wrong fails loudly at build start (`ENOENT` writing the file's
-     * parent directory) rather than silently generating nothing, but it's
-     * still worth setting explicitly if your project doesn't use `src/`.
+     * resolved root. Not needed for the common case — `kbach()` auto-detects
+     * it (see `findMainCSSFile`'s own doc comment) by finding wherever you
+     * actually put the two marker comments, regardless of whether your
+     * project's source root is `src/`, `app/` (React Router v7's framework
+     * mode), or anything else in `include`. Set this explicitly only to
+     * disambiguate a genuinely unusual layout (a marker file outside every
+     * `include` directory, or more than one candidate present at once).
      */
     cssFile?: string;
 }
+/**
+ * Finds where to read/write the `kbach:start`/`kbach:end` marker file,
+ * with no configuration required for the common case:
+ *
+ * 1. An explicit `cssFile` always wins (the one supported escape hatch).
+ * 2. Otherwise, look for a `kbach.css` already containing BOTH markers in
+ *    each `include` directory (in order) and the project root itself —
+ *    wherever you actually created it is where this plugin keeps using it,
+ *    regardless of which framework convention (`src/`, `app/`, ...) that
+ *    is. This is what makes React Router v7's framework mode (`app/
+ *    kbach.css`) and a plain Vite app (`src/kbach.css`) both "just work"
+ *    with the exact same `kbach()` call — no per-framework option needed.
+ * 3. No marked file exists yet (first run in a fresh project) — pick the
+ *    first `include` directory that already exists as a real directory on
+ *    disk, so the file this plugin is about to CREATE lands somewhere that
+ *    won't need its own parent directory made up out of nothing.
+ * 4. Nothing in `include` exists yet either (a genuinely empty project,
+ *    scaffolded before its first source file) — fall back to the first
+ *    configured `include` entry regardless; `writeMainCSSFile` (below)
+ *    creates its parent directory unconditionally, so this never crashes
+ *    even here.
+ */
+declare function findMainCSSFile(root: string, includeDirs: string[], explicitCssFile?: string): string;
 declare const DEFAULT_SCAN_DIRS: string[];
 declare const CSS_SYNC_DEBOUNCE_MS = 50;
 /**
@@ -73,11 +96,12 @@ declare function resolveEffectiveTheme(root: string, options: {
  * Build-time static CSS generation for Vite — scans source files for
  * Kbach class strings, resolves them through the same Rust engine the
  * runtime uses (via the Node-target WASM build, see wasmNode.ts), and
- * writes a real kbach.css. Simplified vs old-kbach's version: expects a
- * marker file to already exist at a fixed conventional path — `src/
- * kbach.css` by default, override via `cssFile` for any other source root
- * (create it with `/* kbach:start *\/` / `/* kbach:end *\/` markers)
- * rather than scanning the whole project for a file named kbach.css.
+ * writes a real kbach.css. Auto-detects WHERE that file is (or should be
+ * created) via `findMainCSSFile` — no per-framework config needed for
+ * `src/`, `app/` (React Router v7's framework mode), or any other
+ * `include` convention; create a file with `/* kbach:start *\/` / `/*
+ * kbach:end *\/` markers wherever your project's source actually lives
+ * and this plugin finds it there.
  *
  * The actual scanning/resolution/generation logic lives in
  * `staticCss/engine.ts`, shared with `postcss-plugin/index.ts` (Next.js/
@@ -87,4 +111,4 @@ declare function resolveEffectiveTheme(root: string, options: {
  */
 declare function kbach(options?: KbachPluginOptions): Plugin;
 
-export { CSS_SYNC_DEBOUNCE_MS, DEFAULT_SCAN_DIRS, type KbachPluginOptions, kbach, loadConfigFile, resolveEffectiveTheme };
+export { CSS_SYNC_DEBOUNCE_MS, DEFAULT_SCAN_DIRS, type KbachPluginOptions, findMainCSSFile, kbach, loadConfigFile, resolveEffectiveTheme };

package/dist/vite-plugin.js

@@ -22,6 +22,7 @@ var vite_plugin_exports = {};
 __export(vite_plugin_exports, {
   CSS_SYNC_DEBOUNCE_MS: () => CSS_SYNC_DEBOUNCE_MS,
   DEFAULT_SCAN_DIRS: () => DEFAULT_SCAN_DIRS,
+  findMainCSSFile: () => findMainCSSFile,
   kbach: () => kbach,
   loadConfigFile: () => loadConfigFile,
   resolveEffectiveTheme: () => resolveEffectiveTheme
@@ -1754,6 +1755,27 @@ function readSourceFile(path) {
 }
 
 // src/vite-plugin/index.ts
+function findMainCSSFile(root, includeDirs, explicitCssFile) {
+  if (explicitCssFile) return (0, import_path4.join)(root, explicitCssFile);
+  const searchDirs = [...includeDirs, "."];
+  for (const dir of searchDirs) {
+    const candidate = (0, import_path4.join)(root, dir, "kbach.css");
+    if (!(0, import_fs3.existsSync)(candidate)) continue;
+    try {
+      const content = (0, import_fs3.readFileSync)(candidate, "utf-8");
+      if (content.includes(KBACH_START) && content.includes(KBACH_END)) return candidate;
+    } catch {
+    }
+  }
+  for (const dir of includeDirs) {
+    const full = (0, import_path4.join)(root, dir);
+    try {
+      if ((0, import_fs3.statSync)(full).isDirectory()) return (0, import_path4.join)(full, "kbach.css");
+    } catch {
+    }
+  }
+  return (0, import_path4.join)(root, includeDirs[0] ?? "src", "kbach.css");
+}
 var DEFAULT_SCAN_DIRS = ["src", "app", "pages", "components"];
 var CSS_SYNC_DEBOUNCE_MS = 50;
 function writeFileEnsuringDir(path, content) {
@@ -1778,8 +1800,9 @@ function kbach(options = {}) {
   let root = process.cwd();
   let theme = defaultTheme;
   let engine = createKbachStaticCssEngine({ root, theme, themeJson: JSON.stringify(theme), includeDirs, safelist });
+  let mainCSSFilePath = (0, import_path4.join)(root, "src", "kbach.css");
   function mainCSSFile() {
-    return (0, import_path4.join)(root, options.cssFile ?? "src/kbach.css");
+    return mainCSSFilePath;
   }
   function classNameHintsFile() {
     return (0, import_path4.join)(root, ".kbach", "kbach-classnames.d.ts");
@@ -1789,7 +1812,7 @@ function kbach(options = {}) {
     writeFileEnsuringDir(classNameHintsFile(), dts);
   }
   function syncMainCSSFile(server) {
-    const changed = writeKbachToFile(mainCSSFile(), engine.generateCSS(), readSourceFile, (p, c) => (0, import_fs3.writeFileSync)(p, c, "utf-8"));
+    const changed = writeKbachToFile(mainCSSFile(), engine.generateCSS(), readSourceFile, writeFileEnsuringDir);
     if (changed && server) server.watcher.emit("change", mainCSSFile());
   }
   let syncTimer = null;
@@ -1807,12 +1830,13 @@ function kbach(options = {}) {
       root = resolved.root;
       theme = resolveEffectiveTheme(root, options);
       engine = createKbachStaticCssEngine({ root, theme, themeJson: JSON.stringify(theme), includeDirs, safelist });
+      mainCSSFilePath = findMainCSSFile(root, includeDirs, options.cssFile);
     },
     buildStart() {
       engine.scanProjectCssSelectorsOnce();
       engine.initialScan();
       engine.processSafelist();
-      writeKbachToFile(mainCSSFile(), engine.generateCSS(), readSourceFile, (p, c) => (0, import_fs3.writeFileSync)(p, c, "utf-8"));
+      writeKbachToFile(mainCSSFile(), engine.generateCSS(), readSourceFile, writeFileEnsuringDir);
       writeClassNameHints();
     },
     // handleHotUpdate covers edits; add/unlink (create/delete) land on the
@@ -1852,6 +1876,7 @@ function kbach(options = {}) {
 0 && (module.exports = {
   CSS_SYNC_DEBOUNCE_MS,
   DEFAULT_SCAN_DIRS,
+  findMainCSSFile,
   kbach,
   loadConfigFile,
   resolveEffectiveTheme

package/dist/vite-plugin.mjs

@@ -1,15 +1,17 @@
 import {
   CSS_SYNC_DEBOUNCE_MS,
   DEFAULT_SCAN_DIRS,
+  findMainCSSFile,
   kbach,
   loadConfigFile,
   resolveEffectiveTheme
-} from "./chunk-P4CQSYIL.mjs";
+} from "./chunk-3E26VMLA.mjs";
 import "./chunk-NKR3PSWO.mjs";
 import "./chunk-N5HCQIBB.mjs";
 export {
   CSS_SYNC_DEBOUNCE_MS,
   DEFAULT_SCAN_DIRS,
+  findMainCSSFile,
   kbach,
   loadConfigFile,
   resolveEffectiveTheme

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kbach/react",
-  "version": "1.0.0-beta.7",
+  "version": "1.0.0-beta.8",
   "description": "A utility-first styling engine for React, powered by a real Rust/WASM core — Tailwind CSS v4 feature parity with Kbach's own color palette.",
   "keywords": ["css", "react", "tailwind", "utility-first", "wasm", "styling"],
   "license": "MIT",