boss-css 0.0.14 → 0.0.16

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Boss CSS contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1 +1,146 @@
-boss-css
+<p align="center">
+  <img src="./boss-logo.webp" alt="Boss CSS logo" width="520" />
+</p>
+
+<h1 align="center">Boss CSS</h1>
+
+<p align="center">
+  Polymorphic, usage-driven CSS-in-JS.
+</p>
+
+<p align="center">
+  <strong>Warning:</strong> Boss CSS is not production-ready yet. Expect breaking changes and stability issues.
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/boss-css"><img src="https://img.shields.io/npm/v/boss-css.svg" alt="npm version" /></a>
+  <a href="./package.json"><img src="https://img.shields.io/npm/l/boss-css.svg" alt="license" /></a>
+</p>
+
+<p align="center">
+  <a href="https://bosscss.com">Website</a> | <a href="https://bosscss.com/docs">Documentation</a>
+</p>
+
+## Table of Contents
+
+- [Key Features](#key-features)
+- [Quick Start](#quick-start)
+- [Examples](#examples)
+- [Strategy Modes](#strategy-modes)
+- [License](#license)
+
+## Key Features
+
+- Polymorphic `$$` authoring with framework-aware runtime adapters.
+- Style props and className parsing in one unified API.
+- Strong generated TypeScript types for style props and prepared components.
+- Plugin-driven parser and prop pipeline (`parser`, `prop`, `strategy`, `use`).
+- Server output and browser runtime support with configurable strategy behavior.
+- Zero-runtime compilation
+- Runtime-only mode for client CSS injection when needed.
+- Token support, pseudo selectors, media/breakpoint props, and nested child selectors.
+- CLI tooling for init/compile/dev workflows.
+
+## Quick Start
+
+Install and scaffold:
+
+```bash
+npx boss-css init
+```
+
+Import the generated runtime once near your app root:
+
+```tsx
+import './.bo$$'
+```
+
+## Examples
+
+Write styles directly with `$$`:
+
+```tsx
+export default function Demo() {
+    return (
+        <$$
+            display="flex"
+            gap={12}
+            padding={16}
+            borderRadius={12}
+            backgroundColor="#111"
+            color="#fff"
+            hover={{ backgroundColor: '#222' }}
+        >
+            Hello Boss CSS
+        </$$>
+    )
+}
+```
+
+ClassName syntax (`prop:value` tokens):
+
+```tsx
+export function Badge() {
+    return (
+        <span className="display:inline-block padding:6_10 border-radius:999 color:white background-color:#ed4b9b">
+            New
+        </span>
+    )
+}
+```
+
+Grouped pseudo and responsive className:
+
+```tsx
+export function Button() {
+    return (
+        <button className="mobile:hover:{color:white;background-color:black} hover:{text-decoration:underline;color:red}">
+            Hover me
+        </button>
+    )
+}
+```
+
+Mix static className and dynamic props:
+
+```tsx
+export function Mixed({ bgColor }: { bgColor: string }) {
+    return <div className="display:flex gap:12 border-radius:12" backgroundColor={bgColor} />
+}
+```
+
+Compose className conditionals with `cx`:
+
+```tsx
+import { cx } from 'boss-css/variants'
+
+const className = cx('display:flex gap:8', { 'hover:color:purple': true })
+```
+
+Bosswind plugin for Tailwind-like utilities:
+
+```tsx
+const Box = () => <div className="flex w:100 bg:blue-500 p:4 hover:bg:blue-700">Tailwind-like Box using classNames</div>
+
+const BoxProps = () => (
+    <$$ flex width="100" bg="blue-500" p="4" hover={{ bg: 'blue-700' }}>
+        Tailwind-like Box using props
+    </$$>
+)
+```
+
+## Strategy Modes
+
+Boss CSS supports multiple output strategies:
+
+- `inline-first` (default): Inline everything that's possible => smallest CSS output, lowest possible unused styles,
+  instant critical CSS.
+- `classname-first`: Use class names everywhere possible, variables for dynamic cases.
+- `classname-only`: Static class parsing with zero runtime output. (aka TailwindCSS).
+- `runtime`: Runtime-only or hybrid behavior, for cases where styles need to be generated at runtime.
+
+Read more: https://bosscss.com/docs/concepts/runtime-strategy
+
+## License
+
+MIT

package/dist/ai/server.cjs

@@ -34,6 +34,7 @@ const STATIC_DOC = `### Syntax
 
 ### Values
 - Prefer unitless numbers (padding:12) and use _ for space-separated values (padding:10_20).
+- Avoid hardcoded default unit suffixes in class tokens (border:1_solid, not border:1px_solid).
 - Prefer arrays for shorthands (padding={[0, 10]}).
 - For custom shadows, use arrays (boxShadow={[1, 1, 0, '#fff']}).
 

package/dist/ai/server.mjs

@@ -32,6 +32,7 @@ const STATIC_DOC = `### Syntax
 
 ### Values
 - Prefer unitless numbers (padding:12) and use _ for space-separated values (padding:10_20).
+- Avoid hardcoded default unit suffixes in class tokens (border:1_solid, not border:1px_solid).
 - Prefer arrays for shorthands (padding={[0, 10]}).
 - For custom shadows, use arrays (boxShadow={[1, 1, 0, '#fff']}).
 

package/dist/ai/skills.cjs

@@ -19,6 +19,7 @@ Apply Boss CSS props cleanly with tokens and selectors.
 - In classname-first, return $$.token.* from dynamic functions when using tokens.
 - Use child for nested selectors instead of manual selector strings.
 - Prefer unitless values (padding:12). Use _ for spaces (padding:10_20).
+- Avoid hardcoded default unit suffixes in class tokens (border:1_solid, not border:1px_solid).
 - Prefer arrays for shorthands (padding={[0, 10]}).
 
 # References
@@ -128,6 +129,7 @@ Write correct className tokens and shorthands.
 # Guidance
 - className tokens are mostly CSS prop:value (1:1 with props).
 - Use unitless values (padding:12), and _ for space-separated values (padding:10_20).
+- Avoid hardcoded default unit suffixes in class tokens (border:1_solid, not border:1px_solid).
 - Prefer shorthand pseudos and breakpoints: hover:color:red, mobile:gap:12.
 - For @at, prefer shorthand (mobile:...) over at:mobile:... when available.
 
@@ -145,6 +147,7 @@ Use Boss-friendly value forms for consistent output.
 
 # Guidance
 - Prefer unitless numbers for numeric props (padding:12).
+- Avoid hardcoded default unit suffixes in class tokens (border:1_solid, not border:1px_solid).
 - Use arrays for shorthands: padding={[0, 10]}.
 - Use token shorthands when available (boxShadow="md").
 - For custom shadow values, use arrays: boxShadow={[1, 1, 0, '#fff']}.

package/dist/ai/skills.mjs

@@ -18,6 +18,7 @@ Apply Boss CSS props cleanly with tokens and selectors.
 - In classname-first, return $$.token.* from dynamic functions when using tokens.
 - Use child for nested selectors instead of manual selector strings.
 - Prefer unitless values (padding:12). Use _ for spaces (padding:10_20).
+- Avoid hardcoded default unit suffixes in class tokens (border:1_solid, not border:1px_solid).
 - Prefer arrays for shorthands (padding={[0, 10]}).
 
 # References
@@ -127,6 +128,7 @@ Write correct className tokens and shorthands.
 # Guidance
 - className tokens are mostly CSS prop:value (1:1 with props).
 - Use unitless values (padding:12), and _ for space-separated values (padding:10_20).
+- Avoid hardcoded default unit suffixes in class tokens (border:1_solid, not border:1px_solid).
 - Prefer shorthand pseudos and breakpoints: hover:color:red, mobile:gap:12.
 - For @at, prefer shorthand (mobile:...) over at:mobile:... when available.
 
@@ -144,6 +146,7 @@ Use Boss-friendly value forms for consistent output.
 
 # Guidance
 - Prefer unitless numbers for numeric props (padding:12).
+- Avoid hardcoded default unit suffixes in class tokens (border:1_solid, not border:1px_solid).
 - Use arrays for shorthands: padding={[0, 10]}.
 - Use token shorthands when available (boxShadow="md").
 - For custom shadow values, use arrays: boxShadow={[1, 1, 0, '#fff']}.

package/dist/cli/tasks/init.cjs

@@ -255,8 +255,8 @@ const init = async (config) => {
 			packageJson
 		});
 		const isStencil = framework.id === "stencil";
-		const cssAutoLoad = !isStencil;
-		const detectedSrcRoot = await detectSrcRoot(cwd);
+		const cssAutoLoad = !isStencil && !isNext;
+		const detectedSrcRoot = await detectSrcRoot(cwd, isNext);
 		const normalizedSrcRoot = normalizeRelativePath(await resolveTextValue({
 			label: "Where is your source root?",
 			value: flags.srcRoot,
@@ -301,7 +301,7 @@ const init = async (config) => {
 			enabled: shouldConfigureEslint
 		});
 		const outputDir = node_path.default.resolve(cwd, normalizedConfigDir);
-		if (!await confirmOverwriteIfExists(outputDir, flags.yes)) return false;
+		const overwriteMode = await confirmOverwriteIfExists(outputDir, flags.yes, flags.overwrite);
 		const contentGlobs = buildContentGlobs({
 			srcRoot: normalizedSrcRoot,
 			isNext
@@ -353,7 +353,8 @@ const init = async (config) => {
 			srcRoot: normalizedSrcRoot,
 			configDir: normalizedConfigDir,
 			globalsEnabled,
-			cssAutoLoad
+			cssAutoLoad,
+			overwriteConfigDir: overwriteMode === "overwrite"
 		});
 		await generateRuntime({
 			outputDir,
@@ -362,7 +363,8 @@ const init = async (config) => {
 			contentGlobs,
 			globalsEnabled,
 			cssAutoLoad,
-			selectedStrategyId
+			selectedStrategyId,
+			overwriteConfigDir: overwriteMode === "overwrite"
 		});
 		if (isStencil) await ensureStencilSetup({
 			cwd,
@@ -525,7 +527,8 @@ const parseFlags = (argv) => {
 		strategy: getStringArg(argv, ["strategy"]),
 		postcss: normalizePostcssMode(getArg(argv, ["postcss"])) ?? void 0,
 		globals: normalizeBooleanArg(getArg(argv, ["globals"])),
-		eslintPlugin: normalizeBooleanArg(getArg(argv, ["eslintPlugin", "eslint-plugin"]))
+		eslintPlugin: normalizeBooleanArg(getArg(argv, ["eslintPlugin", "eslint-plugin"])),
+		overwrite: normalizeBooleanArg(getArg(argv, ["overwrite"]))
 	};
 };
 const getArg = (argv, keys) => {
@@ -556,7 +559,11 @@ const normalizePostcssMode = (value) => {
 		if (normalized === "auto" || normalized === "manual" || normalized === "skip") return normalized;
 	}
 };
-const detectSrcRoot = async (cwd) => {
+const detectSrcRoot = async (cwd, isNext) => {
+	if (isNext) {
+		if (await exists(node_path.default.join(cwd, "src"))) return "src";
+		return ".";
+	}
 	for (const candidate of [
 		"src",
 		"app",
@@ -1304,7 +1311,7 @@ const findMatchingIndex = (content, startIndex, openChar, closeChar) => {
 	}
 	return -1;
 };
-const writeInitFiles = async ({ outputDir, configFolder, contentGlobs, pluginState, selectedStrategyId, isNext, postcssMode, postcssDetection, includeAutoprefixer, packageJson, dirDependencies, usePostcssOptions, srcRoot, configDir, globalsEnabled, cssAutoLoad }) => {
+const writeInitFiles = async ({ outputDir, configFolder, contentGlobs, pluginState, selectedStrategyId, isNext, postcssMode, postcssDetection, includeAutoprefixer, packageJson, dirDependencies, usePostcssOptions, srcRoot, configDir, globalsEnabled, cssAutoLoad, overwriteConfigDir }) => {
 	await node_fs_promises.default.mkdir(outputDir, { recursive: true });
 	const isRuntimeStrategy = selectedStrategyId === "runtime-only" || selectedStrategyId === "runtime-hybrid";
 	const configText = (0, pluvo.default)(require_init.configTemplate, {
@@ -1318,9 +1325,9 @@ const writeInitFiles = async ({ outputDir, configFolder, contentGlobs, pluginSta
 		runtimeOnly: selectedStrategyId === "runtime-only",
 		cssAutoLoad
 	}, { commentStyles: INIT_COMMENT_STYLES });
-	await writeFile(node_path.default.join(outputDir, "config.js"), configText);
-	await writeFile(node_path.default.join(outputDir, "jsconfig.json"), require_init.jsconfigTemplate);
-	await writeFile(node_path.default.join(outputDir, "package.json"), require_init.packageTemplate);
+	await writeFile(node_path.default.join(outputDir, "config.js"), configText, overwriteConfigDir);
+	await writeFile(node_path.default.join(outputDir, "jsconfig.json"), require_init.jsconfigTemplate, overwriteConfigDir);
+	await writeFile(node_path.default.join(outputDir, "package.json"), require_init.packageTemplate, overwriteConfigDir);
 	await ensureFile(node_path.default.join(outputDir, "styles.css"));
 	if (postcssMode === "auto") {
 		if (!postcssDetection.hasConfigFile && !postcssDetection.hasPackageConfig) {
@@ -1530,22 +1537,35 @@ const getImportInsertIndex = (lines) => {
 	}
 	return index;
 };
-const generateRuntime = async ({ outputDir, configFolder, pluginState, contentGlobs, globalsEnabled, cssAutoLoad, selectedStrategyId }) => {
+const generateRuntime = async ({ outputDir, configFolder, pluginState, contentGlobs, globalsEnabled, cssAutoLoad, selectedStrategyId, overwriteConfigDir }) => {
 	if (selectedStrategyId === "classname-only") return;
 	const enabledPlugins = pluginState.filter((plugin) => plugin.enabled);
+	const hasJsxPlugin = enabledPlugins.some((plugin) => plugin.id === "jsx");
 	const modules = enabledPlugins.map((plugin) => PLUGIN_MODULES[plugin.id]).filter(Boolean);
-	if (globalsEnabled && enabledPlugins.some((plugin) => plugin.id === "jsx")) require_parser_jsx_server.settings.set?.("globals", true);
-	if (enabledPlugins.some((plugin) => plugin.id === "jsx")) require_parser_jsx_server.settings.set?.("emitRuntime", true);
+	if (hasJsxPlugin) require_parser_jsx_server.settings.set?.("emitRuntime", true);
 	if (enabledPlugins.some((plugin) => plugin.id === "inline-first")) require_strategy_inline_first_server.settings.set?.("emitRuntime", true);
 	if (enabledPlugins.some((plugin) => plugin.id === "classname-first")) require_strategy_classname_first_server.settings.set?.("emitRuntime", true);
 	const api = await require_api_server.createApi({
 		folder: configFolder,
 		plugins: modules,
 		content: contentGlobs,
+		jsx: hasJsxPlugin ? { globals: globalsEnabled } : void 0,
 		css: cssAutoLoad ? void 0 : { autoLoad: false }
 	}, true);
-	await api.file.js.write();
-	if (api.file.native?.hasContent) await api.file.native.write();
+	const jsText = api.file.js.text;
+	if (jsText) {
+		await writeFile(node_path.default.join(outputDir, api.file.js.options.path), jsText, overwriteConfigDir);
+		const dtsText = api.file.js.dts.text;
+		if (dtsText) await writeFile(node_path.default.join(outputDir, api.file.js.dts.options.path), dtsText, overwriteConfigDir);
+	}
+	if (api.file.native?.hasContent) {
+		const nativeText = api.file.native.text;
+		if (nativeText) {
+			await writeFile(node_path.default.join(outputDir, api.file.native.options.path), nativeText, overwriteConfigDir);
+			const nativeDtsText = api.file.native.dts.text;
+			if (nativeDtsText) await writeFile(node_path.default.join(outputDir, api.file.native.dts.options.path), nativeDtsText, overwriteConfigDir);
+		}
+	}
 };
 const warnIfPostcssPluginMissing = async (configFilePath) => {
 	if ((await node_fs_promises.default.readFile(configFilePath, "utf-8")).includes("boss-css/postcss")) return;
@@ -1696,15 +1716,17 @@ const getIndentFromIndex = (content, index) => {
 	const match = content.slice(lineStart + 1).match(/^\s+/);
 	return match ? match[0] : "";
 };
-const confirmOverwriteIfExists = async (dirPath, yes) => {
-	if (!await exists(dirPath)) return true;
-	if (yes) return true;
-	const shouldContinue = await (0, _clack_prompts.confirm)({
-		message: `Existing ${node_path.default.basename(dirPath)} folder detected. Overwrite its contents?`,
+const confirmOverwriteIfExists = async (dirPath, yes, overwrite) => {
+	if (!await exists(dirPath)) return "overwrite";
+	if (overwrite === false) return "merge";
+	if (overwrite === true) return "overwrite";
+	if (yes) return "overwrite";
+	const shouldOverwrite = await (0, _clack_prompts.confirm)({
+		message: `Existing ${node_path.default.basename(dirPath)} folder detected. Overwrite its contents? (No keeps existing files)`,
 		initialValue: false
 	});
-	require_utils.cancelIf(shouldContinue);
-	return shouldContinue;
+	require_utils.cancelIf(shouldOverwrite);
+	return shouldOverwrite ? "overwrite" : "merge";
 };
 const readPackageJson = async (cwd) => {
 	const filePath = node_path.default.join(cwd, "package.json");
@@ -1728,8 +1750,12 @@ const writePackageJson = async (cwd, data, indent, newline) => {
 	const output = JSON.stringify(data, null, indent) + (newline || "\n");
 	await node_fs_promises.default.writeFile(filePath, output);
 };
-const writeFile = async (filePath, content) => {
+const writeFile = async (filePath, content, overwrite = true) => {
 	await node_fs_promises.default.mkdir(node_path.default.dirname(filePath), { recursive: true });
+	if (!overwrite) try {
+		await node_fs_promises.default.access(filePath);
+		return;
+	} catch {}
 	await node_fs_promises.default.writeFile(filePath, content.trimEnd() + "\n");
 };
 const ensureFile = async (filePath) => {
@@ -1804,16 +1830,14 @@ const logInitSummary = ({ configDir, isNext, postcssMode, postcssDetection, conf
 	if (isNext) {
 		_clack_prompts.log.message("Next.js note:");
 		if (selectedStrategyId === "classname-only") {
-			const importRoot = normalizeImportPath(node_path.default.relative(srcRoot, configDir));
-			const importStyles = normalizeImportPath(node_path.default.join(importRoot, "styles.css"));
-			_clack_prompts.log.message(`- Classname-only mode skips instrumentation. Import ${importStyles} in your app entry.`);
+			_clack_prompts.log.message("- Classname-only mode skips instrumentation.");
+			_clack_prompts.log.message("- Import Boss styles manually in your root layout (e.g. `import '../.bo$$/styles.css'`).");
 		} else {
 			_clack_prompts.log.message("- Updated instrumentation files with Boss CSS imports.");
 			_clack_prompts.log.message("Boss PostCSS auto-disables dirDependencies when a Turbopack env flag is set.");
 			if (!cssAutoLoad) {
-				const importRoot = normalizeImportPath(node_path.default.relative(srcRoot, configDir));
-				const importStyles = normalizeImportPath(node_path.default.join(importRoot, "styles.css"));
-				_clack_prompts.log.message(`- css.autoLoad is false. Import ${importStyles} in your app entry.`);
+				_clack_prompts.log.message("- css.autoLoad is false.");
+				_clack_prompts.log.message("- Import Boss styles manually in your root layout (e.g. `import '../.bo$$/styles.css'`).");
 			}
 		}
 	} else {

package/dist/cli/tasks/init.mjs

@@ -251,8 +251,8 @@ const init = async (config) => {
 			packageJson
 		});
 		const isStencil = framework.id === "stencil";
-		const cssAutoLoad = !isStencil;
-		const detectedSrcRoot = await detectSrcRoot(cwd);
+		const cssAutoLoad = !isStencil && !isNext;
+		const detectedSrcRoot = await detectSrcRoot(cwd, isNext);
 		const normalizedSrcRoot = normalizeRelativePath(await resolveTextValue({
 			label: "Where is your source root?",
 			value: flags.srcRoot,
@@ -297,7 +297,7 @@ const init = async (config) => {
 			enabled: shouldConfigureEslint
 		});
 		const outputDir = path.resolve(cwd, normalizedConfigDir);
-		if (!await confirmOverwriteIfExists(outputDir, flags.yes)) return false;
+		const overwriteMode = await confirmOverwriteIfExists(outputDir, flags.yes, flags.overwrite);
 		const contentGlobs = buildContentGlobs({
 			srcRoot: normalizedSrcRoot,
 			isNext
@@ -349,7 +349,8 @@ const init = async (config) => {
 			srcRoot: normalizedSrcRoot,
 			configDir: normalizedConfigDir,
 			globalsEnabled,
-			cssAutoLoad
+			cssAutoLoad,
+			overwriteConfigDir: overwriteMode === "overwrite"
 		});
 		await generateRuntime({
 			outputDir,
@@ -358,7 +359,8 @@ const init = async (config) => {
 			contentGlobs,
 			globalsEnabled,
 			cssAutoLoad,
-			selectedStrategyId
+			selectedStrategyId,
+			overwriteConfigDir: overwriteMode === "overwrite"
 		});
 		if (isStencil) await ensureStencilSetup({
 			cwd,
@@ -521,7 +523,8 @@ const parseFlags = (argv) => {
 		strategy: getStringArg(argv, ["strategy"]),
 		postcss: normalizePostcssMode(getArg(argv, ["postcss"])) ?? void 0,
 		globals: normalizeBooleanArg(getArg(argv, ["globals"])),
-		eslintPlugin: normalizeBooleanArg(getArg(argv, ["eslintPlugin", "eslint-plugin"]))
+		eslintPlugin: normalizeBooleanArg(getArg(argv, ["eslintPlugin", "eslint-plugin"])),
+		overwrite: normalizeBooleanArg(getArg(argv, ["overwrite"]))
 	};
 };
 const getArg = (argv, keys) => {
@@ -552,7 +555,11 @@ const normalizePostcssMode = (value) => {
 		if (normalized === "auto" || normalized === "manual" || normalized === "skip") return normalized;
 	}
 };
-const detectSrcRoot = async (cwd) => {
+const detectSrcRoot = async (cwd, isNext) => {
+	if (isNext) {
+		if (await exists(path.join(cwd, "src"))) return "src";
+		return ".";
+	}
 	for (const candidate of [
 		"src",
 		"app",
@@ -1300,7 +1307,7 @@ const findMatchingIndex = (content, startIndex, openChar, closeChar) => {
 	}
 	return -1;
 };
-const writeInitFiles = async ({ outputDir, configFolder, contentGlobs, pluginState, selectedStrategyId, isNext, postcssMode, postcssDetection, includeAutoprefixer, packageJson, dirDependencies, usePostcssOptions, srcRoot, configDir, globalsEnabled, cssAutoLoad }) => {
+const writeInitFiles = async ({ outputDir, configFolder, contentGlobs, pluginState, selectedStrategyId, isNext, postcssMode, postcssDetection, includeAutoprefixer, packageJson, dirDependencies, usePostcssOptions, srcRoot, configDir, globalsEnabled, cssAutoLoad, overwriteConfigDir }) => {
 	await fs.mkdir(outputDir, { recursive: true });
 	const isRuntimeStrategy = selectedStrategyId === "runtime-only" || selectedStrategyId === "runtime-hybrid";
 	const configText = pluvo(configTemplate, {
@@ -1314,9 +1321,9 @@ const writeInitFiles = async ({ outputDir, configFolder, contentGlobs, pluginSta
 		runtimeOnly: selectedStrategyId === "runtime-only",
 		cssAutoLoad
 	}, { commentStyles: INIT_COMMENT_STYLES });
-	await writeFile(path.join(outputDir, "config.js"), configText);
-	await writeFile(path.join(outputDir, "jsconfig.json"), jsconfigTemplate);
-	await writeFile(path.join(outputDir, "package.json"), packageTemplate);
+	await writeFile(path.join(outputDir, "config.js"), configText, overwriteConfigDir);
+	await writeFile(path.join(outputDir, "jsconfig.json"), jsconfigTemplate, overwriteConfigDir);
+	await writeFile(path.join(outputDir, "package.json"), packageTemplate, overwriteConfigDir);
 	await ensureFile(path.join(outputDir, "styles.css"));
 	if (postcssMode === "auto") {
 		if (!postcssDetection.hasConfigFile && !postcssDetection.hasPackageConfig) {
@@ -1526,22 +1533,35 @@ const getImportInsertIndex = (lines) => {
 	}
 	return index;
 };
-const generateRuntime = async ({ outputDir, configFolder, pluginState, contentGlobs, globalsEnabled, cssAutoLoad, selectedStrategyId }) => {
+const generateRuntime = async ({ outputDir, configFolder, pluginState, contentGlobs, globalsEnabled, cssAutoLoad, selectedStrategyId, overwriteConfigDir }) => {
 	if (selectedStrategyId === "classname-only") return;
 	const enabledPlugins = pluginState.filter((plugin) => plugin.enabled);
+	const hasJsxPlugin = enabledPlugins.some((plugin) => plugin.id === "jsx");
 	const modules = enabledPlugins.map((plugin) => PLUGIN_MODULES[plugin.id]).filter(Boolean);
-	if (globalsEnabled && enabledPlugins.some((plugin) => plugin.id === "jsx")) settings.set?.("globals", true);
-	if (enabledPlugins.some((plugin) => plugin.id === "jsx")) settings.set?.("emitRuntime", true);
+	if (hasJsxPlugin) settings.set?.("emitRuntime", true);
 	if (enabledPlugins.some((plugin) => plugin.id === "inline-first")) settings$1.set?.("emitRuntime", true);
 	if (enabledPlugins.some((plugin) => plugin.id === "classname-first")) settings$2.set?.("emitRuntime", true);
 	const api = await createApi({
 		folder: configFolder,
 		plugins: modules,
 		content: contentGlobs,
+		jsx: hasJsxPlugin ? { globals: globalsEnabled } : void 0,
 		css: cssAutoLoad ? void 0 : { autoLoad: false }
 	}, true);
-	await api.file.js.write();
-	if (api.file.native?.hasContent) await api.file.native.write();
+	const jsText = api.file.js.text;
+	if (jsText) {
+		await writeFile(path.join(outputDir, api.file.js.options.path), jsText, overwriteConfigDir);
+		const dtsText = api.file.js.dts.text;
+		if (dtsText) await writeFile(path.join(outputDir, api.file.js.dts.options.path), dtsText, overwriteConfigDir);
+	}
+	if (api.file.native?.hasContent) {
+		const nativeText = api.file.native.text;
+		if (nativeText) {
+			await writeFile(path.join(outputDir, api.file.native.options.path), nativeText, overwriteConfigDir);
+			const nativeDtsText = api.file.native.dts.text;
+			if (nativeDtsText) await writeFile(path.join(outputDir, api.file.native.dts.options.path), nativeDtsText, overwriteConfigDir);
+		}
+	}
 };
 const warnIfPostcssPluginMissing = async (configFilePath) => {
 	if ((await fs.readFile(configFilePath, "utf-8")).includes("boss-css/postcss")) return;
@@ -1692,15 +1712,17 @@ const getIndentFromIndex = (content, index) => {
 	const match = content.slice(lineStart + 1).match(/^\s+/);
 	return match ? match[0] : "";
 };
-const confirmOverwriteIfExists = async (dirPath, yes) => {
-	if (!await exists(dirPath)) return true;
-	if (yes) return true;
-	const shouldContinue = await confirm({
-		message: `Existing ${path.basename(dirPath)} folder detected. Overwrite its contents?`,
+const confirmOverwriteIfExists = async (dirPath, yes, overwrite) => {
+	if (!await exists(dirPath)) return "overwrite";
+	if (overwrite === false) return "merge";
+	if (overwrite === true) return "overwrite";
+	if (yes) return "overwrite";
+	const shouldOverwrite = await confirm({
+		message: `Existing ${path.basename(dirPath)} folder detected. Overwrite its contents? (No keeps existing files)`,
 		initialValue: false
 	});
-	cancelIf(shouldContinue);
-	return shouldContinue;
+	cancelIf(shouldOverwrite);
+	return shouldOverwrite ? "overwrite" : "merge";
 };
 const readPackageJson = async (cwd) => {
 	const filePath = path.join(cwd, "package.json");
@@ -1724,8 +1746,12 @@ const writePackageJson = async (cwd, data, indent, newline) => {
 	const output = JSON.stringify(data, null, indent) + (newline || "\n");
 	await fs.writeFile(filePath, output);
 };
-const writeFile = async (filePath, content) => {
+const writeFile = async (filePath, content, overwrite = true) => {
 	await fs.mkdir(path.dirname(filePath), { recursive: true });
+	if (!overwrite) try {
+		await fs.access(filePath);
+		return;
+	} catch {}
 	await fs.writeFile(filePath, content.trimEnd() + "\n");
 };
 const ensureFile = async (filePath) => {
@@ -1800,16 +1826,14 @@ const logInitSummary = ({ configDir, isNext, postcssMode, postcssDetection, conf
 	if (isNext) {
 		log.message("Next.js note:");
 		if (selectedStrategyId === "classname-only") {
-			const importRoot = normalizeImportPath(path.relative(srcRoot, configDir));
-			const importStyles = normalizeImportPath(path.join(importRoot, "styles.css"));
-			log.message(`- Classname-only mode skips instrumentation. Import ${importStyles} in your app entry.`);
+			log.message("- Classname-only mode skips instrumentation.");
+			log.message("- Import Boss styles manually in your root layout (e.g. `import '../.bo$$/styles.css'`).");
 		} else {
 			log.message("- Updated instrumentation files with Boss CSS imports.");
 			log.message("Boss PostCSS auto-disables dirDependencies when a Turbopack env flag is set.");
 			if (!cssAutoLoad) {
-				const importRoot = normalizeImportPath(path.relative(srcRoot, configDir));
-				const importStyles = normalizeImportPath(path.join(importRoot, "styles.css"));
-				log.message(`- css.autoLoad is false. Import ${importStyles} in your app entry.`);
+				log.message("- css.autoLoad is false.");
+				log.message("- Import Boss styles manually in your root layout (e.g. `import '../.bo$$/styles.css'`).");
 			}
 		}
 	} else {

package/dist/cli/templates/init.cjs

@@ -8,15 +8,15 @@ import * as /* @@@ echo $.plugin.importName */token/* @@@ endecho */ from '/* @@
 // @@@ endif
 // @@@ endeach
 
-// @@@ if $.jsxEnabled && $.globalsEnabled
-// globalThis.$$
-jsx.settings.set('globals', true)
-// @@@ endif
-
 /** @type {import('boss-css/api/config').UserConfig} */
 export default {
     // Path from your project root
     folder: /* @@@ echo JSON.stringify($.folder) */'./.bo$$'/* @@@ endecho */,
+// @@@ if $.jsxEnabled
+    jsx: {
+        globals: /* @@@ echo $.globalsEnabled ? 'true' : 'false' */true/* @@@ endecho */,
+    },
+// @@@ endif
 // @@@ if $.cssAutoLoad === false
     css: {
         autoLoad: false,

package/dist/cli/templates/init.mjs

@@ -7,15 +7,15 @@ import * as /* @@@ echo $.plugin.importName */token/* @@@ endecho */ from '/* @@
 // @@@ endif
 // @@@ endeach
 
-// @@@ if $.jsxEnabled && $.globalsEnabled
-// globalThis.$$
-jsx.settings.set('globals', true)
-// @@@ endif
-
 /** @type {import('boss-css/api/config').UserConfig} */
 export default {
     // Path from your project root
     folder: /* @@@ echo JSON.stringify($.folder) */'./.bo$$'/* @@@ endecho */,
+// @@@ if $.jsxEnabled
+    jsx: {
+        globals: /* @@@ echo $.globalsEnabled ? 'true' : 'false' */true/* @@@ endecho */,
+    },
+// @@@ endif
 // @@@ if $.cssAutoLoad === false
     css: {
         autoLoad: false,