@letstri/oxc-config 0.3.1 → 0.5.0

package/README.md

@@ -10,9 +10,28 @@ Opinionated, shared [oxlint](https://oxc.rs/docs/guide/usage/linter.html) and [o
 ## Install
 
 ```bash
-pnpm add -D @letstri/oxc-config oxlint oxfmt
+npm i -D @letstri/oxc-config oxlint oxfmt
 ```
 
+Then scaffold everything with the `oxc-config` CLI:
+
+```bash
+npx oxc-config init
+```
+
+`init` prompts you to pick what to set up — oxlint config, oxfmt config, VS Code,
+Zed. Pass flags to skip the prompt (useful in CI/scripts):
+
+```bash
+npx oxc-config init --oxlint --oxfmt   # just the config files
+npx oxc-config init --vscode --zed     # just the editor settings
+```
+
+With flags, only the chosen targets run; with none in a non-interactive shell,
+all four run. Config files are skipped if they already exist (`--force` to
+overwrite); editor settings are deep-merged into any existing files. See
+[Editor setup](#editor-setup).
+
 ## AI setup prompt
 
 Paste this into Claude Code, Cursor, or any coding agent to wire everything up:
@@ -121,9 +140,20 @@ export default oxlintConfig(
 ```
 
 Because arguments are merged (not spread), Tailwind's plugins combine with the
-ones above rather than overwriting them. `entryPoint` (required) is your Tailwind
-entry CSS, so the plugin can resolve class names. The plugin is an **optional
-peer dependency** — install it yourself:
+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
@@ -136,119 +166,26 @@ 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.
+`oxc-config init` writes (or updates) the editor configs for you, deep-merging
+into any existing files so your other settings are kept:
 
-<details>
-<summary>Show VS Code config</summary>
-
-`.vscode/extensions.json`:
-
-```json
-{
-  "recommendations": ["oxc.oxc-vscode"]
-}
-```
-
-`.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
-  },
-}
+```bash
+# both editors
+pnpm exec oxc-config init --vscode --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 (`init --vscode` also adds it to `.vscode/extensions.json`). It 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.
+`init --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 } from "node:path";
+import { cancel, isCI, isCancel, multiselect } from "@clack/prompts";
+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
+const log = (message) => process.stdout.write(`${message}\n`);
+const merge = createDefu((obj, key, value) => {
+	const current = obj[key];
+	if (Array.isArray(current) && Array.isArray(value)) {
+		const union = [...value, ...current].map((item) => JSON.stringify(item));
+		obj[key] = [...new Set(union)].map((item) => JSON.parse(item));
+		return true;
+	}
+	return false;
+});
+function mergeJson(path, base) {
+	const existed = existsSync(path);
+	const current = existed ? parse(readFileSync(path, "utf-8"), [], { allowTrailingComma: true }) : {};
+	mkdirSync(dirname(path), { recursive: true });
+	writeFileSync(path, `${JSON.stringify(merge(base, current ?? {}), null, 2)}\n`);
+	return existed ? "updated" : "created";
+}
+function writeConfig(path, content, force) {
+	const existed = existsSync(path);
+	if (existed && !force) return "skipped";
+	writeFileSync(path, content);
+	return existed ? "overwritten" : "created";
+}
+const template = (fn) => `import { ${fn} } from '@letstri/oxc-config'\n\nexport default ${fn}()\n`;
+const TARGETS = {
+	oxlint: {
+		label: "oxlint.config.ts",
+		run: (force) => `oxlint: ${writeConfig("oxlint.config.ts", template("oxlintConfig"), force)}`
+	},
+	oxfmt: {
+		label: "oxfmt.config.ts",
+		run: (force) => `oxfmt: ${writeConfig("oxfmt.config.ts", template("oxfmtConfig"), force)}`
+	},
+	vscode: {
+		label: "VS Code settings (.vscode)",
+		run: () => `vscode: ${mergeJson(".vscode/settings.json", vscodeSettings)} settings, ${mergeJson(".vscode/extensions.json", vscodeExtensions)} extensions`
+	},
+	zed: {
+		label: "Zed settings (.zed)",
+		run: () => `zed: ${mergeJson(".zed/settings.json", zedSettings)}`
+	}
+};
+const ALL = Object.keys(TARGETS);
+async function pickTargets(flags) {
+	const flagged = ALL.filter((target) => flags.has(`--${target}`));
+	if (flagged.length > 0) return flagged;
+	if (isCI() || !process.stdout.isTTY) return ALL;
+	const selected = await multiselect({
+		message: "What do you want to set up?",
+		options: ALL.map((value) => ({
+			value,
+			label: TARGETS[value].label
+		})),
+		initialValues: ALL,
+		required: true
+	});
+	if (isCancel(selected)) {
+		cancel("Cancelled.");
+		return null;
+	}
+	return selected;
+}
+function version() {
+	const url = new URL("../package.json", import.meta.url);
+	return JSON.parse(readFileSync(url, "utf-8")).version;
+}
+const HELP = `oxc-config — set up @letstri/oxc-config in your project
+
+Usage:
+  oxc-config [flags]
+
+Flags (default: prompt for what to set up):
+  --oxlint       create oxlint.config.ts
+  --oxfmt        create oxfmt.config.ts
+  --vscode       write .vscode settings
+  --zed          write .zed settings
+  -f, --force    overwrite existing config files
+  -h, --help     show this help
+  -v, --version  show version`;
+const argv = process.argv.slice(2);
+if (argv.includes("--help") || argv.includes("-h")) log(HELP);
+else if (argv.includes("--version") || argv.includes("-v")) log(version());
+else {
+	const flags = new Set(argv);
+	const force = flags.has("--force") || flags.has("-f");
+	const targets = await pickTargets(flags);
+	for (const target of targets ?? []) log(TARGETS[target].run(force));
+}
+//#endregion
+export {};

package/dist/index.d.mts

@@ -50,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.
    *
@@ -62,13 +67,16 @@ interface TailwindOptions {
  * 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

@@ -586,14 +586,17 @@ const TAILWIND_PLUGIN = "eslint-plugin-better-tailwindcss";
 * 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],
@@ -606,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.3.1",
+  "version": "0.5.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"
+    "@clack/prompts": "^1.7.0",
+    "defu": "^6.1.7",
+    "jsonc-parser": "^3.3.1"
   },
   "devDependencies": {
     "@types/node": "^26.1.1",