@letstri/oxc-config 0.2.1 → 0.4.0

package/README.md

@@ -4,15 +4,25 @@ Opinionated, shared [oxlint](https://oxc.rs/docs/guide/usage/linter.html) and [o
 
 > [!NOTE]
 > This is an **opinionated** config — it ships a curated set of rules and
-> formatting defaults meant to work out of the box. Override anything you
-> disagree with via the [`override`](#overrides) option.
+> formatting defaults meant to work out of the box. [Override](#overrides)
+> anything you disagree with.
 
 ## Install
 
 ```bash
-pnpm add -D @letstri/oxc-config oxlint oxfmt
+npm i -D @letstri/oxc-config oxlint oxfmt
 ```
 
+Then scaffold the config files and editor settings with the `oxc-config` CLI:
+
+```bash
+npx oxc-config config    # create oxlint.config.ts + oxfmt.config.ts
+npx oxc-config editors   # write .vscode + .zed settings
+```
+
+Run `oxc-config --help` for all commands. Details: [Usage](#usage) and
+[Editor setup](#editor-setup).
+
 ## AI setup prompt
 
 Paste this into Claude Code, Cursor, or any coding agent to wire everything up:
@@ -44,7 +54,7 @@ Set up @letstri/oxc-config (oxlint + oxfmt) in this project:
    - "format:check": "oxfmt --check"
 6. Framework plugins auto-enable from the nearest package.json. If a framework
    dep (react/vue/next/vitest/jest/typescript) lives in a nested workspace,
-   enable it manually, e.g. `oxlintConfig({ vue: true })`.
+   enable it manually, e.g. `oxlintConfig({ plugins: ['vue'] })`.
 7. Add the VS Code and Zed editor settings from the @letstri/oxc-config README.
 8. Run `pnpm lint` and `pnpm format` and fix anything reported.
 ````
@@ -96,33 +106,45 @@ export default oxlintConfig({
 
 ### Overrides
 
-Anything you pass to `oxlintConfig` / `oxfmtConfig` is deep-merged over the base
-config via [defu](https://github.com/unjs/defu):
+`oxlintConfig` / `oxfmtConfig` accept **any number of config objects**, all
+deep-merged over the base config via [defu](https://github.com/unjs/defu) (arrays
+are concatenated, so plugins from different pieces combine instead of
+overwriting):
 
 ```ts
-export default oxlintConfig({
-  rules: {
-    'no-console': 'off',
-  },
-})
+export default oxlintConfig({ rules: { 'no-console': 'off' } }, { plugins: ['vue'] })
 ```
 
 ### Tailwind
 
 `tailwind({ entryPoint })` returns a config chunk for
 [`eslint-plugin-better-tailwindcss`](https://github.com/schoero/eslint-plugin-better-tailwindcss).
-Spread it into `oxlintConfig`:
+Pass it as an argument to `oxlintConfig`:
 
 ```ts
 import { oxlintConfig, tailwind } from '@letstri/oxc-config'
 
-export default oxlintConfig({
-  ...tailwind({ entryPoint: 'app/globals.css' }),
-})
+export default oxlintConfig(
+  { plugins: ['react', 'jsx-a11y'] },
+  tailwind({ entryPoint: 'app/globals.css' }),
+)
 ```
 
-`entryPoint` (required) is your Tailwind entry CSS, so the plugin can resolve
-class names. The plugin is an **optional peer dependency** — install it yourself:
+Because arguments are merged (not spread), Tailwind's plugins combine with the
+ones above rather than overwriting them.
+
+Options:
+
+- `entryPoint` (required) — your Tailwind entry CSS, so the plugin can resolve
+  class names.
+- `ignoreClasses` — class names to exempt from `no-unknown-classes` (e.g. classes
+  a component library generates that the plugin can't resolve):
+
+  ```ts
+  tailwind({ entryPoint: 'app/globals.css', ignoreClasses: ['toaster'] })
+  ```
+
+The plugin is an **optional peer dependency** — install it yourself:
 
 ```bash
 pnpm add -D eslint-plugin-better-tailwindcss
@@ -135,119 +157,30 @@ If the plugin is missing, `tailwind()` throws with an install hint.
 Both editors use the official [oxc](https://oxc.rs) tooling — `oxlint` for
 linting and `oxfmt` for formatting — replacing ESLint and Prettier.
 
-### VS Code
-
-Install the [`oxc.oxc-vscode`](https://marketplace.visualstudio.com/items?itemName=oxc.oxc-vscode)
-extension.
-
-<details>
-<summary>Show VS Code config</summary>
-
-`.vscode/extensions.json`:
+The `oxc-config editors` command writes (or updates) the editor configs for you,
+deep-merging into any existing files so your other settings are kept:
 
-```json
-{
-  "recommendations": ["oxc.oxc-vscode"]
-}
-```
+```bash
+# both editors
+pnpm exec oxc-config editors
 
-`.vscode/settings.json`:
-
-```jsonc
-{
-  "oxc.configPath": "oxlint.config.ts",
-  "oxc.fmt.configPath": "oxfmt.config.ts",
-  "oxc.typeAware": true,
-  "oxc.unusedDisableDirectives": "deny",
-  "oxc.enable": true,
-  "prettier.enable": false,
-  "editor.defaultFormatter": "oxc.oxc-vscode",
-  "editor.formatOnSave": true,
-  "editor.formatOnSaveMode": "file", // oxfmt can only format whole files
-  "editor.codeActionsOnSave": {
-    "source.fixAll.oxc": "explicit",
-    "source.organizeImports": "never", // let oxfmt handle import organization
-  },
-}
+# or just one
+pnpm exec oxc-config editors --vscode
+pnpm exec oxc-config editors --zed
 ```
 
-</details>
+It's idempotent — safe to re-run to pull the latest recommended settings.
 
-### Zed
-
-Zed ships with the oxc language servers built in.
+### VS Code
 
-<details>
-<summary>Show Zed config</summary>
-
-`.zed/settings.json`:
-
-```jsonc
-{
-  "lsp": {
-    "oxlint": {
-      "initialization_options": {
-        "settings": {
-          "configPath": null,
-          "run": "onType",
-          "disableNestedConfig": false,
-          "fixKind": "safe_fix",
-          "unusedDisableDirectives": "deny",
-        },
-      },
-    },
-    "oxfmt": {
-      "initialization_options": {
-        "settings": {
-          "fmt.configPath": null,
-          "run": "onSave",
-        },
-      },
-    },
-  },
-  "languages": {
-    "TypeScript": {
-      "format_on_save": "on",
-      "prettier": { "allowed": false },
-      "language_servers": ["...", "oxlint", "oxfmt"],
-      "formatter": [
-        { "language_server": { "name": "oxfmt" } },
-        { "code_action": "source.fixAll.oxc" },
-      ],
-    },
-    "TSX": {
-      "format_on_save": "on",
-      "prettier": { "allowed": false },
-      "language_servers": ["...", "oxlint", "oxfmt"],
-      "formatter": [
-        { "language_server": { "name": "oxfmt" } },
-        { "code_action": "source.fixAll.oxc" },
-      ],
-    },
-    "JavaScript": {
-      "format_on_save": "on",
-      "prettier": { "allowed": false },
-      "language_servers": ["...", "oxlint", "oxfmt"],
-      "formatter": [
-        { "language_server": { "name": "oxfmt" } },
-        { "code_action": "source.fixAll.oxc" },
-      ],
-    },
-    "JSON": {
-      "format_on_save": "on",
-      "prettier": { "allowed": false },
-      "formatter": [{ "language_server": { "name": "oxfmt" } }],
-    },
-    "Markdown": {
-      "format_on_save": "on",
-      "prettier": { "allowed": false },
-      "formatter": [{ "language_server": { "name": "oxfmt" } }],
-    },
-  },
-}
-```
+Install the [`oxc.oxc-vscode`](https://marketplace.visualstudio.com/items?itemName=oxc.oxc-vscode)
+extension (`oxc-config editors --vscode` also adds it to `.vscode/extensions.json`). The
+CLI writes `.vscode/settings.json` — oxlint as linter, oxfmt as the default
+formatter with format-on-save, and Prettier's import organization turned off.
 
-Apply the same `languages` block to any other file types you want oxfmt to
-format (`JSONC`, `CSS`, `HTML`, `YAML`, …).
+### Zed
 
-</details>
+Zed ships with the oxc language servers built in, so no extension is needed.
+`oxc-config editors --zed` writes `.zed/settings.json` — oxfmt as the formatter (with
+`source.fixAll.oxc` on save for JS/TS) and Prettier disabled, across the file
+types oxfmt supports.

package/dist/cli.d.mts

@@ -0,0 +1 @@
+export { };

package/dist/cli.mjs

@@ -0,0 +1,165 @@
+#!/usr/bin/env node
+import process from "node:process";
+import { createDefu } from "defu";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { boolean, command, run } from "@drizzle-team/brocli";
+import { parse } from "jsonc-parser";
+//#region src/editors.ts
+/**
+* Editor config templates, adapted from the official oxc examples:
+* - https://github.com/oxc-project/oxc-vscode/blob/main/.vscode/settings.json
+* - https://github.com/oxc-project/oxc-zed/blob/main/examples/both/.zed/settings.json
+*
+* `configPath` values point at this library's TypeScript config files.
+*/
+const vscodeExtensions = { recommendations: ["oxc.oxc-vscode"] };
+const vscodeSettings = {
+	"oxc.configPath": "oxlint.config.ts",
+	"oxc.fmt.configPath": "oxfmt.config.ts",
+	"oxc.typeAware": true,
+	"oxc.unusedDisableDirectives": "deny",
+	"editor.defaultFormatter": "oxc.oxc-vscode",
+	"editor.formatOnSave": true,
+	"editor.formatOnSaveMode": "file",
+	"editor.codeActionsOnSave": { "source.organizeImports": "never" }
+};
+const oxfmtFormatter = { language_server: { name: "oxfmt" } };
+function formatOnSave(withFix = false) {
+	return {
+		format_on_save: "on",
+		prettier: { allowed: false },
+		formatter: withFix ? [oxfmtFormatter, { code_action: "source.fixAll.oxc" }] : [oxfmtFormatter]
+	};
+}
+const cssLike = [
+	"CSS",
+	"GraphQL",
+	"Handlebars",
+	"HTML",
+	"JSON",
+	"JSON5",
+	"JSONC",
+	"Less",
+	"Markdown",
+	"MDX",
+	"SCSS",
+	"YAML"
+];
+const codeLike = [
+	"JavaScript",
+	"TypeScript",
+	"TSX",
+	"Vue.js"
+];
+const zedSettings = {
+	lsp: {
+		oxlint: { initialization_options: { settings: {
+			configPath: null,
+			run: "onType",
+			disableNestedConfig: false,
+			fixKind: "safe_fix",
+			unusedDisableDirectives: "deny"
+		} } },
+		oxfmt: { initialization_options: { settings: {
+			"fmt.configPath": null,
+			"run": "onSave"
+		} } }
+	},
+	languages: {
+		...Object.fromEntries(cssLike.map((lang) => [lang, formatOnSave()])),
+		...Object.fromEntries(codeLike.map((lang) => [lang, formatOnSave(true)]))
+	}
+};
+//#endregion
+//#region src/cli.ts
+/**
+* Like defu, but arrays are merged as a de-duplicated union instead of being
+* concatenated — keeps updates idempotent and preserves user-added entries.
+*/
+const mergeConfig = createDefu((obj, key, value) => {
+	const current = obj[key];
+	if (Array.isArray(current) && Array.isArray(value)) {
+		const seen = /* @__PURE__ */ new Set();
+		obj[key] = [...value, ...current].filter((item) => {
+			const id = JSON.stringify(item);
+			if (seen.has(id)) return false;
+			seen.add(id);
+			return true;
+		});
+		return true;
+	}
+	return false;
+});
+function readJsonc(path) {
+	if (!existsSync(path)) return {};
+	return parse(readFileSync(path, "utf-8"), [], { allowTrailingComma: true }) ?? {};
+}
+/** Deep-merge `base` into the JSON(C) file at `path`, creating it if absent. */
+function mergeJsonFile(path, base) {
+	const existed = existsSync(path);
+	const merged = mergeConfig(base, readJsonc(path));
+	mkdirSync(dirname(path), { recursive: true });
+	writeFileSync(path, `${JSON.stringify(merged, null, 2)}\n`);
+	return existed ? "updated" : "created";
+}
+/** Write `content` to `path`, skipping an existing file unless `force`. */
+function writeFile(path, content, force) {
+	const existed = existsSync(path);
+	if (existed && !force) return "skipped";
+	mkdirSync(dirname(path), { recursive: true });
+	writeFileSync(path, content);
+	return existed ? "overwritten" : "created";
+}
+const OXLINT_CONFIG = `import { oxlintConfig } from '@letstri/oxc-config'
+
+export default oxlintConfig()
+`;
+const OXFMT_CONFIG = `import { oxfmtConfig } from '@letstri/oxc-config'
+
+export default oxfmtConfig()
+`;
+function version() {
+	try {
+		return JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf-8")).version ?? "0.0.0";
+	} catch {
+		return "0.0.0";
+	}
+}
+run([command({
+	name: "config",
+	desc: "Create oxlint.config.ts and oxfmt.config.ts",
+	options: { force: boolean().alias("f").desc("Overwrite existing files").default(false) },
+	handler: ({ force }) => {
+		const cwd = process.cwd();
+		const lint = writeFile(resolve(cwd, "oxlint.config.ts"), OXLINT_CONFIG, force);
+		const fmt = writeFile(resolve(cwd, "oxfmt.config.ts"), OXFMT_CONFIG, force);
+		process.stdout.write(`config: ${lint} oxlint.config.ts, ${fmt} oxfmt.config.ts\n`);
+	}
+}), command({
+	name: "editors",
+	desc: "Write/update VS Code and Zed editor configs (deep-merged into existing files)",
+	options: {
+		vscode: boolean().desc("Only VS Code").default(false),
+		zed: boolean().desc("Only Zed").default(false)
+	},
+	handler: ({ vscode, zed }) => {
+		const both = !vscode && !zed;
+		const cwd = process.cwd();
+		if (both || vscode) {
+			const s = mergeJsonFile(resolve(cwd, ".vscode/settings.json"), vscodeSettings);
+			const e = mergeJsonFile(resolve(cwd, ".vscode/extensions.json"), vscodeExtensions);
+			process.stdout.write(`vscode: ${s} .vscode/settings.json, ${e} .vscode/extensions.json\n`);
+		}
+		if (both || zed) {
+			const s = mergeJsonFile(resolve(cwd, ".zed/settings.json"), zedSettings);
+			process.stdout.write(`zed: ${s} .zed/settings.json\n`);
+		}
+	}
+})], {
+	name: "oxc-config",
+	description: "Set up @letstri/oxc-config in your project",
+	version: version()
+});
+//#endregion
+export {};

package/dist/index.d.mts

@@ -8,7 +8,10 @@ type OxlintOptions$1 = Parameters<typeof defineConfig>[0];
  * Plugins are auto-enabled by detecting their package (`typescript`, `react`,
  * `vue`, `next`, `vitest`, `jest`) in the nearest `package.json`. To enable a
  * plugin whose dependency lives elsewhere — e.g. a nested workspace like
- * `apps/web/package.json` — add it through `overrides.plugins`.
+ * `apps/web/package.json` — add it through `plugins`.
+ *
+ * Pass any number of config objects; they are deep-merged (arrays concatenated),
+ * so pieces like {@link tailwind} compose without clobbering each other.
  *
  * @example
  * ```ts
@@ -22,15 +25,22 @@ type OxlintOptions$1 = Parameters<typeof defineConfig>[0];
  * ```
  * @example
  * ```ts
- * // add Tailwind linting
- * export default oxlintConfig({ ...tailwind({ entryPoint: 'app/globals.css' }) })
+ * // compose Tailwind — its plugins merge with the ones above, not overwrite
+ * export default oxlintConfig(
+ *   { plugins: ['react', 'jsx-a11y'] },
+ *   tailwind({ entryPoint: 'app/globals.css' }),
+ * )
  * ```
  */
-declare function oxlintConfig(overrides?: OxlintOptions$1): OxlintOptions$1;
+declare function oxlintConfig(...overrides: OxlintOptions$1[]): OxlintOptions$1;
 //#endregion
 //#region src/oxfmt.d.ts
 type OxfmtOptions = Parameters<typeof defineConfig$1>[0];
-declare function oxfmtConfig(overrides?: OxfmtOptions): OxfmtOptions;
+/**
+ * Build an oxfmt config. Pass any number of config objects; they are deep-merged
+ * over the base config via defu.
+ */
+declare function oxfmtConfig(...overrides: OxfmtOptions[]): OxfmtOptions;
 //#endregion
 //#region src/tailwind.d.ts
 type OxlintOptions = Parameters<typeof defineConfig>[0];
@@ -40,6 +50,11 @@ interface TailwindOptions {
    * class names.
    */
   entryPoint: string;
+  /**
+   * Class names to exempt from `no-unknown-classes` — e.g. classes generated by
+   * component libraries that the plugin can't resolve from the entry CSS.
+   */
+  ignoreClasses?: string[];
   /**
    * Directory scanned to check the plugin is installed.
    *
@@ -49,16 +64,19 @@ interface TailwindOptions {
 }
 /**
  * Tailwind linting via [`eslint-plugin-better-tailwindcss`](https://github.com/schoero/eslint-plugin-better-tailwindcss).
- * Spread the result into `oxlintConfig`:
+ * Pass the result as an argument to `oxlintConfig`:
  *
  * ```ts
- * export default oxlintConfig({ ...tailwind({ entryPoint: 'app/globals.css' }) })
+ * export default oxlintConfig(tailwind({
+ *   entryPoint: 'app/globals.css',
+ *   ignoreClasses: ['toaster'],
+ * }))
  * ```
  *
  * The plugin is an optional peer dependency — install it yourself
  * (`pnpm add -D eslint-plugin-better-tailwindcss`). If it is missing, an error
  * is thrown.
  */
-declare function tailwind({ entryPoint, cwd }: TailwindOptions): OxlintOptions;
+declare function tailwind({ entryPoint, ignoreClasses, cwd }: TailwindOptions): OxlintOptions;
 //#endregion
 export { oxfmtConfig, oxlintConfig, tailwind };

package/dist/index.mjs

@@ -534,7 +534,10 @@ function resolvePlugins(cwd) {
 * Plugins are auto-enabled by detecting their package (`typescript`, `react`,
 * `vue`, `next`, `vitest`, `jest`) in the nearest `package.json`. To enable a
 * plugin whose dependency lives elsewhere — e.g. a nested workspace like
-* `apps/web/package.json` — add it through `overrides.plugins`.
+* `apps/web/package.json` — add it through `plugins`.
+*
+* Pass any number of config objects; they are deep-merged (arrays concatenated),
+* so pieces like {@link tailwind} compose without clobbering each other.
 *
 * @example
 * ```ts
@@ -548,41 +551,52 @@ function resolvePlugins(cwd) {
 * ```
 * @example
 * ```ts
-* // add Tailwind linting
-* export default oxlintConfig({ ...tailwind({ entryPoint: 'app/globals.css' }) })
+* // compose Tailwind — its plugins merge with the ones above, not overwrite
+* export default oxlintConfig(
+*   { plugins: ['react', 'jsx-a11y'] },
+*   tailwind({ entryPoint: 'app/globals.css' }),
+* )
 * ```
 */
-function oxlintConfig(overrides = {}) {
-	return defu(overrides, { plugins: resolvePlugins(process.cwd()) }, baseOxlintConfig);
+function oxlintConfig(...overrides) {
+	return defu({}, ...overrides, { plugins: resolvePlugins(process.cwd()) }, baseOxlintConfig);
 }
 //#endregion
 //#region src/oxfmt.ts
 const baseOxfmtConfig = defineConfig$1({
+	printWidth: 100,
 	singleQuote: true,
 	semi: false,
 	arrowParens: "avoid",
 	sortImports: true,
 	quoteProps: "consistent"
 });
-function oxfmtConfig(overrides = {}) {
-	return defu(overrides, baseOxfmtConfig);
+/**
+* Build an oxfmt config. Pass any number of config objects; they are deep-merged
+* over the base config via defu.
+*/
+function oxfmtConfig(...overrides) {
+	return defu({}, ...overrides, baseOxfmtConfig);
 }
 //#endregion
 //#region src/tailwind.ts
 const TAILWIND_PLUGIN = "eslint-plugin-better-tailwindcss";
 /**
 * Tailwind linting via [`eslint-plugin-better-tailwindcss`](https://github.com/schoero/eslint-plugin-better-tailwindcss).
-* Spread the result into `oxlintConfig`:
+* Pass the result as an argument to `oxlintConfig`:
 *
 * ```ts
-* export default oxlintConfig({ ...tailwind({ entryPoint: 'app/globals.css' }) })
+* export default oxlintConfig(tailwind({
+*   entryPoint: 'app/globals.css',
+*   ignoreClasses: ['toaster'],
+* }))
 * ```
 *
 * The plugin is an optional peer dependency — install it yourself
 * (`pnpm add -D eslint-plugin-better-tailwindcss`). If it is missing, an error
 * is thrown.
 */
-function tailwind({ entryPoint, cwd = process.cwd() }) {
+function tailwind({ entryPoint, ignoreClasses = [], cwd = process.cwd() }) {
 	if (!getInstalledPackages(cwd).has(TAILWIND_PLUGIN)) throw new Error(`[@letstri/oxc-config] Tailwind linting needs "${TAILWIND_PLUGIN}". Install it: pnpm add -D ${TAILWIND_PLUGIN}`);
 	return defineConfig({
 		jsPlugins: [TAILWIND_PLUGIN],
@@ -595,7 +609,7 @@ function tailwind({ entryPoint, cwd = process.cwd() }) {
 			"better-tailwindcss/no-conflicting-classes": "error",
 			"better-tailwindcss/no-deprecated-classes": "error",
 			"better-tailwindcss/no-duplicate-classes": "error",
-			"better-tailwindcss/no-unknown-classes": "error"
+			"better-tailwindcss/no-unknown-classes": ["error", { ignore: ignoreClasses }]
 		}
 	});
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@letstri/oxc-config",
-  "version": "0.2.1",
+  "version": "0.4.0",
   "description": "Opinionated Oxlint and Oxfmt configs",
   "homepage": "https://github.com/letstri/oxc-config#readme",
   "bugs": {
@@ -12,6 +12,9 @@
     "type": "git",
     "url": "git+https://github.com/letstri/oxc-config.git"
   },
+  "bin": {
+    "oxc-config": "./dist/cli.mjs"
+  },
   "files": [
     "dist"
   ],
@@ -28,7 +31,9 @@
     "access": "public"
   },
   "dependencies": {
-    "defu": "^6.1.7"
+    "@drizzle-team/brocli": "^0.12.0",
+    "defu": "^6.1.7",
+    "jsonc-parser": "^3.3.1"
   },
   "devDependencies": {
     "@types/node": "^26.1.1",