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

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-7JBSTM5D.mjs}

@@ -7,8 +7,9 @@ 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 { pathToFileURL } from "url";
 import { createRequire } from "module";
 
 // src/vite-plugin/cssVars.ts
@@ -1235,22 +1236,63 @@ 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) {
   mkdirSync(dirname(path), { recursive: true });
   writeFileSync(path, content, "utf-8");
 }
-function loadConfigFile(root) {
-  const path = join4(root, "kbach.config.js");
-  if (!existsSync(path)) return void 0;
+function isEsmRequireFailure(err) {
+  if (!(err instanceof Error)) return false;
+  return err.code === "ERR_REQUIRE_ESM" || /is not defined in ES module scope/.test(err.message);
+}
+async function importConfigModule(path) {
+  const mod = await import(pathToFileURL(path).href);
+  return mod.default ?? mod;
+}
+function requireConfigModule(root, path) {
   const mod = createRequire(root)(path);
   return mod.default ?? mod;
 }
-function resolveEffectiveTheme(root, options) {
+async function loadConfigFile(root) {
+  const cjsPath = join4(root, "kbach.config.cjs");
+  if (existsSync(cjsPath)) return requireConfigModule(root, cjsPath);
+  const mjsPath = join4(root, "kbach.config.mjs");
+  if (existsSync(mjsPath)) return importConfigModule(mjsPath);
+  const jsPath = join4(root, "kbach.config.js");
+  if (!existsSync(jsPath)) return void 0;
+  try {
+    return requireConfigModule(root, jsPath);
+  } catch (err) {
+    if (!isEsmRequireFailure(err)) throw err;
+    return importConfigModule(jsPath);
+  }
+}
+async function resolveEffectiveTheme(root, options) {
   if (options.theme) return options.theme;
   if (options.config) return resolveKbachConfig(options.config);
-  const discovered = loadConfigFile(root);
+  const discovered = await loadConfigFile(root);
   return discovered ? resolveKbachConfig(discovered) : defaultTheme;
 }
 function kbach(options = {}) {
@@ -1259,8 +1301,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 +1313,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;
@@ -1284,16 +1327,17 @@ function kbach(options = {}) {
   return {
     name: "kbach",
     enforce: "pre",
-    configResolved(resolved) {
+    async configResolved(resolved) {
       root = resolved.root;
-      theme = resolveEffectiveTheme(root, options);
+      theme = await 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 +1376,7 @@ function kbach(options = {}) {
 
 export {
   createKbachStaticCssEngine,
+  findMainCSSFile,
   DEFAULT_SCAN_DIRS,
   CSS_SYNC_DEBOUNCE_MS,
   loadConfigFile,

package/dist/postcss-plugin.js

@@ -618,6 +618,7 @@ function createKbachStaticCssEngine(options) {
 // src/vite-plugin/index.ts
 var import_fs2 = require("fs");
 var import_path4 = require("path");
+var import_url = require("url");
 var import_module = require("module");
 
 // src/generatedPalette.ts
@@ -1038,16 +1039,36 @@ function resolveKbachConfig(config) {
 
 // src/vite-plugin/index.ts
 var DEFAULT_SCAN_DIRS = ["src", "app", "pages", "components"];
-function loadConfigFile(root) {
-  const path = (0, import_path4.join)(root, "kbach.config.js");
-  if (!(0, import_fs2.existsSync)(path)) return void 0;
+function isEsmRequireFailure(err) {
+  if (!(err instanceof Error)) return false;
+  return err.code === "ERR_REQUIRE_ESM" || /is not defined in ES module scope/.test(err.message);
+}
+async function importConfigModule(path) {
+  const mod = await import((0, import_url.pathToFileURL)(path).href);
+  return mod.default ?? mod;
+}
+function requireConfigModule(root, path) {
   const mod = (0, import_module.createRequire)(root)(path);
   return mod.default ?? mod;
 }
-function resolveEffectiveTheme(root, options) {
+async function loadConfigFile(root) {
+  const cjsPath = (0, import_path4.join)(root, "kbach.config.cjs");
+  if ((0, import_fs2.existsSync)(cjsPath)) return requireConfigModule(root, cjsPath);
+  const mjsPath = (0, import_path4.join)(root, "kbach.config.mjs");
+  if ((0, import_fs2.existsSync)(mjsPath)) return importConfigModule(mjsPath);
+  const jsPath = (0, import_path4.join)(root, "kbach.config.js");
+  if (!(0, import_fs2.existsSync)(jsPath)) return void 0;
+  try {
+    return requireConfigModule(root, jsPath);
+  } catch (err) {
+    if (!isEsmRequireFailure(err)) throw err;
+    return importConfigModule(jsPath);
+  }
+}
+async function resolveEffectiveTheme(root, options) {
   if (options.theme) return options.theme;
   if (options.config) return resolveKbachConfig(options.config);
-  const discovered = loadConfigFile(root);
+  const discovered = await loadConfigFile(root);
   return discovered ? resolveKbachConfig(discovered) : defaultTheme;
 }
 
@@ -1089,9 +1110,9 @@ function spliceGeneratedCss(root, generatedCss) {
 function kbachPostcss(options = {}) {
   return {
     postcssPlugin: "kbach",
-    Once(root, { result }) {
+    async Once(root, { result }) {
       const projectRoot = options.root ?? process.cwd();
-      const theme = resolveEffectiveTheme(projectRoot, options);
+      const theme = await resolveEffectiveTheme(projectRoot, options);
       const includeDirs = options.include ?? DEFAULT_SCAN_DIRS;
       const safelist = options.safelist ?? [];
       const engine = createKbachStaticCssEngine({

package/dist/postcss-plugin.mjs

@@ -2,7 +2,7 @@ import {
   DEFAULT_SCAN_DIRS,
   createKbachStaticCssEngine,
   resolveEffectiveTheme
-} from "./chunk-P4CQSYIL.mjs";
+} from "./chunk-7JBSTM5D.mjs";
 import "./chunk-NKR3PSWO.mjs";
 import "./chunk-N5HCQIBB.mjs";
 
@@ -46,9 +46,9 @@ function spliceGeneratedCss(root, generatedCss) {
 function kbachPostcss(options = {}) {
   return {
     postcssPlugin: "kbach",
-    Once(root, { result }) {
+    async Once(root, { result }) {
       const projectRoot = options.root ?? process.cwd();
-      const theme = resolveEffectiveTheme(projectRoot, options);
+      const theme = await resolveEffectiveTheme(projectRoot, options);
       const includeDirs = options.include ?? DEFAULT_SCAN_DIRS;
       const safelist = options.safelist ?? [];
       const engine = createKbachStaticCssEngine({

package/dist/vite-plugin.d.mts

@@ -29,37 +29,76 @@ 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;
 /**
- * Auto-discovers `kbach.config.js` at the project root — `undefined` if it
- * doesn't exist (the common case: most projects have no customization at
+ * Auto-discovers a `kbach.config.*` file at the project root — `undefined`
+ * if none exists (the common case: most projects have no customization at
  * all, so this is a silent, expected no-op, not a warning).
  *
- * Uses `require()` (a real project's `kbach.config.js` is plain CommonJS,
- * `module.exports = {...}`, matching every example in this package's own
- * README), built via `createRequire(root)` rather than
+ * Checks three filenames, in order, mirroring Node's own module-format
+ * conventions rather than assuming one: `kbach.config.cjs` (always
+ * CommonJS, `module.exports = {...}` — the one unambiguous choice
+ * regardless of the project's package.json) and `kbach.config.mjs`
+ * (always real ESM, `export default {...}`) are tried first, each loaded
+ * the one way that's guaranteed correct for that extension. Only the bare
+ * `kbach.config.js` — whose actual meaning depends on the nearest
+ * package.json's `"type"` field, exactly like every other `.js` file in
+ * the project — needs the fallback below: try `require()` first (correct
+ * for `"type": "commonjs"`/no `"type"` field, the more common case), and
+ * only on a failure that specifically indicates an ESM/CJS mismatch (see
+ * `isEsmRequireFailure`), retry via a real dynamic `import()` instead. A
+ * genuine syntax error in an otherwise-correctly-formatted config file is
+ * NOT caught here — it propagates as a real, actionable build failure,
+ * rather than being silently swallowed into a confusing second attempt.
+ *
+ * `require()` is built via `createRequire(root)` rather than
  * `createRequire(import.meta.url)` — this file is written as ESM source,
  * but tsup's CJS build output has no real `import.meta.url` (esbuild
  * leaves it `undefined` there), which would make `createRequire` throw for
  * anyone consuming this package's `require('@kbach/react/vite')` entry.
  * `root` works as `createRequire`'s base in either build: it's always an
- * absolute, already-`existsSync`-validated-by-caller directory, and
- * `require()` given `path` (itself already absolute) doesn't consult the
- * base for resolution anyway — the base only matters for a RELATIVE
- * specifier, which this never passes it.
+ * absolute, already-`existsSync`-validated directory, and `require()`
+ * given an already-absolute `path` doesn't consult the base for
+ * resolution anyway — the base only matters for a relative specifier,
+ * which this never passes it. `import()` needs a real `file://` URL, not
+ * a bare Windows path (`C:\...` isn't a valid ESM specifier) — hence
+ * `pathToFileURL`.
  */
-declare function loadConfigFile(root: string): KbachConfig | undefined;
+declare function loadConfigFile(root: string): Promise<KbachConfig | undefined>;
 /**
  * Resolves the theme to use, applying the same "explicit theme/config
  * always wins over kbach.config.js auto-discovery" precedence both
@@ -68,16 +107,17 @@ declare function loadConfigFile(root: string): KbachConfig | undefined;
 declare function resolveEffectiveTheme(root: string, options: {
     theme?: ThemeConfig;
     config?: KbachConfig;
-}): ThemeConfig;
+}): Promise<ThemeConfig>;
 /**
  * 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 +127,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,37 +29,76 @@ 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;
 /**
- * Auto-discovers `kbach.config.js` at the project root — `undefined` if it
- * doesn't exist (the common case: most projects have no customization at
+ * Auto-discovers a `kbach.config.*` file at the project root — `undefined`
+ * if none exists (the common case: most projects have no customization at
  * all, so this is a silent, expected no-op, not a warning).
  *
- * Uses `require()` (a real project's `kbach.config.js` is plain CommonJS,
- * `module.exports = {...}`, matching every example in this package's own
- * README), built via `createRequire(root)` rather than
+ * Checks three filenames, in order, mirroring Node's own module-format
+ * conventions rather than assuming one: `kbach.config.cjs` (always
+ * CommonJS, `module.exports = {...}` — the one unambiguous choice
+ * regardless of the project's package.json) and `kbach.config.mjs`
+ * (always real ESM, `export default {...}`) are tried first, each loaded
+ * the one way that's guaranteed correct for that extension. Only the bare
+ * `kbach.config.js` — whose actual meaning depends on the nearest
+ * package.json's `"type"` field, exactly like every other `.js` file in
+ * the project — needs the fallback below: try `require()` first (correct
+ * for `"type": "commonjs"`/no `"type"` field, the more common case), and
+ * only on a failure that specifically indicates an ESM/CJS mismatch (see
+ * `isEsmRequireFailure`), retry via a real dynamic `import()` instead. A
+ * genuine syntax error in an otherwise-correctly-formatted config file is
+ * NOT caught here — it propagates as a real, actionable build failure,
+ * rather than being silently swallowed into a confusing second attempt.
+ *
+ * `require()` is built via `createRequire(root)` rather than
  * `createRequire(import.meta.url)` — this file is written as ESM source,
  * but tsup's CJS build output has no real `import.meta.url` (esbuild
  * leaves it `undefined` there), which would make `createRequire` throw for
  * anyone consuming this package's `require('@kbach/react/vite')` entry.
  * `root` works as `createRequire`'s base in either build: it's always an
- * absolute, already-`existsSync`-validated-by-caller directory, and
- * `require()` given `path` (itself already absolute) doesn't consult the
- * base for resolution anyway — the base only matters for a RELATIVE
- * specifier, which this never passes it.
+ * absolute, already-`existsSync`-validated directory, and `require()`
+ * given an already-absolute `path` doesn't consult the base for
+ * resolution anyway — the base only matters for a relative specifier,
+ * which this never passes it. `import()` needs a real `file://` URL, not
+ * a bare Windows path (`C:\...` isn't a valid ESM specifier) — hence
+ * `pathToFileURL`.
  */
-declare function loadConfigFile(root: string): KbachConfig | undefined;
+declare function loadConfigFile(root: string): Promise<KbachConfig | undefined>;
 /**
  * Resolves the theme to use, applying the same "explicit theme/config
  * always wins over kbach.config.js auto-discovery" precedence both
@@ -68,16 +107,17 @@ declare function loadConfigFile(root: string): KbachConfig | undefined;
 declare function resolveEffectiveTheme(root: string, options: {
     theme?: ThemeConfig;
     config?: KbachConfig;
-}): ThemeConfig;
+}): Promise<ThemeConfig>;
 /**
  * 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 +127,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
@@ -29,6 +30,7 @@ __export(vite_plugin_exports, {
 module.exports = __toCommonJS(vite_plugin_exports);
 var import_fs3 = require("fs");
 var import_path4 = require("path");
+var import_url = require("url");
 var import_module = require("module");
 
 // src/vite-plugin/cssVars.ts
@@ -1754,22 +1756,63 @@ 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) {
   (0, import_fs3.mkdirSync)((0, import_path4.dirname)(path), { recursive: true });
   (0, import_fs3.writeFileSync)(path, content, "utf-8");
 }
-function loadConfigFile(root) {
-  const path = (0, import_path4.join)(root, "kbach.config.js");
-  if (!(0, import_fs3.existsSync)(path)) return void 0;
+function isEsmRequireFailure(err) {
+  if (!(err instanceof Error)) return false;
+  return err.code === "ERR_REQUIRE_ESM" || /is not defined in ES module scope/.test(err.message);
+}
+async function importConfigModule(path) {
+  const mod = await import((0, import_url.pathToFileURL)(path).href);
+  return mod.default ?? mod;
+}
+function requireConfigModule(root, path) {
   const mod = (0, import_module.createRequire)(root)(path);
   return mod.default ?? mod;
 }
-function resolveEffectiveTheme(root, options) {
+async function loadConfigFile(root) {
+  const cjsPath = (0, import_path4.join)(root, "kbach.config.cjs");
+  if ((0, import_fs3.existsSync)(cjsPath)) return requireConfigModule(root, cjsPath);
+  const mjsPath = (0, import_path4.join)(root, "kbach.config.mjs");
+  if ((0, import_fs3.existsSync)(mjsPath)) return importConfigModule(mjsPath);
+  const jsPath = (0, import_path4.join)(root, "kbach.config.js");
+  if (!(0, import_fs3.existsSync)(jsPath)) return void 0;
+  try {
+    return requireConfigModule(root, jsPath);
+  } catch (err) {
+    if (!isEsmRequireFailure(err)) throw err;
+    return importConfigModule(jsPath);
+  }
+}
+async function resolveEffectiveTheme(root, options) {
   if (options.theme) return options.theme;
   if (options.config) return resolveKbachConfig(options.config);
-  const discovered = loadConfigFile(root);
+  const discovered = await loadConfigFile(root);
   return discovered ? resolveKbachConfig(discovered) : defaultTheme;
 }
 function kbach(options = {}) {
@@ -1778,8 +1821,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 +1833,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;
@@ -1803,16 +1847,17 @@ function kbach(options = {}) {
   return {
     name: "kbach",
     enforce: "pre",
-    configResolved(resolved) {
+    async configResolved(resolved) {
       root = resolved.root;
-      theme = resolveEffectiveTheme(root, options);
+      theme = await 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 +1897,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-7JBSTM5D.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.9",
   "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",