@ovt2/biome-react-kit 0.0.0-stage → 2.3.0

package/README.md

@@ -1,3 +1,201 @@
-# Temporary Holding Version
+# @ovt2/biome-react-kit
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Shared Biome lint/format/check preset for our React apps.
+
+## Setup
+
+One command installs Biome and the kit, writes `biome.json`, adds the
+`check`/`check:fix` scripts, and wires up the pre-commit hook and CI workflow:
+
+```sh
+bunx @ovt2/biome-react-kit init
+```
+
+Options:
+
+| Flag              | Effect                                             |
+| ----------------- | -------------------------------------------------- |
+| `--preset <name>` | `base` (default), `strict`, or `next`              |
+| `--no-hooks`      | Skip husky + the pre-commit hook                   |
+| `--no-ci`         | Skip the GitHub Actions workflow                   |
+| `--skip-install`  | Print the install commands instead of running them |
+| `-h, --help`      | Show usage                                         |
+
+`init` never overwrites an existing `biome.json`/`biome.jsonc`, script, hook,
+or workflow file — running it again is safe and only reports what's missing.
+
+`init` itself always runs through `bunx` (the script is a Bun executable),
+but it doesn't require your project to use Bun: it detects your package
+manager from the `packageManager` field in `package.json`, or otherwise from
+whichever lockfile is present (`bun.lock`, `package-lock.json`,
+`pnpm-lock.yaml`, `yarn.lock`), and uses that package manager's install
+command and CI setup. It falls back to Bun only when none of those is
+found. The pre-commit hook always calls the locally installed
+`node_modules/.bin/biome`, so it works the same regardless of which package
+manager installed it.
+
+## CLI commands
+
+Beyond `init`, the kit's own CLI wraps the Biome binary it already installed
+in your project, so you never have to know Biome's own flags. Once it's
+installed, use the short `biome-kit` alias instead of the full package name
+— `bunx` resolves it from `node_modules/.bin` without touching the network:
+
+```sh
+bunx biome-kit check            # biome check .
+bunx biome-kit check:fix        # biome check --write .
+bunx biome-kit ci               # biome ci --reporter=github .
+bunx biome-kit check src/foo.ts # pass specific paths through
+```
+
+(The full name `@ovt2/biome-react-kit` still works everywhere `biome-kit`
+does — it's the same binary under two names. You only _need_ the full name
+once, for the very first `init`, since `bunx` has to resolve that from the
+registry before anything is installed locally.)
+
+These require Bun to invoke (same as `init`), since the CLI itself is a Bun
+script. The `check`/`check:fix` scripts that `init` writes into your
+`package.json` call `biome` directly instead, so `npm run check` (or
+`pnpm`/`yarn run check`) stays Bun-free for everyday use — the CLI commands
+above are a convenience for anyone who already has Bun and wants one
+consistent command across projects.
+
+See the [Command reference](#command-reference) below for every flag and
+manual (non-CLI) setup path.
+
+## Presets
+
+| Name                                 | Extends path            | Use case                                                                                         |
+| ------------------------------------ | ----------------------- | ------------------------------------------------------------------------------------------------ |
+| `@ovt2/biome-react-kit/biome`        | `./presets/base.json`   | Default: recommended rules + React domain, warns on unused code/console.                         |
+| `@ovt2/biome-react-kit/biome/strict` | `./presets/strict.json` | Base rules raised to errors (unused code, `any`, non-null assertions, console, exhaustive deps). |
+| `@ovt2/biome-react-kit/biome/next`   | `./presets/next.json`   | Base preset plus the Next.js lint domain.                                                        |
+
+Presets intentionally don't set `files.includes` — setting it in your own
+`biome.json` would _replace_ the kit's, not merge with it. For Next.js apps,
+add your own ignores:
+
+```json
+{
+  "extends": ["@ovt2/biome-react-kit/biome/next"],
+  "files": { "includes": ["**", "!**/.next", "!**/out", "!**/next-env.d.ts"] }
+}
+```
+
+Add scripts:
+
+```json
+"check": "biome check .",
+"check:fix": "biome check --write ."
+```
+
+## Command reference
+
+Every command this kit provides, for every case.
+
+### `init` — one-time project setup
+
+```sh
+# Default: base preset, installs husky + CI workflow
+bunx @ovt2/biome-react-kit init
+
+# Pick a different preset
+bunx @ovt2/biome-react-kit init --preset strict
+bunx @ovt2/biome-react-kit init --preset next
+
+# Skip the pre-commit hook (no husky install, no .husky/pre-commit, no "prepare" script)
+bunx @ovt2/biome-react-kit init --no-hooks
+
+# Skip the GitHub Actions workflow (no .github/workflows/biome.yml)
+bunx @ovt2/biome-react-kit init --no-ci
+
+# Don't install anything — just print the install command and write the
+# files that don't depend on packages being present yet
+bunx @ovt2/biome-react-kit init --skip-install
+
+# Combine flags freely
+bunx @ovt2/biome-react-kit init --preset next --no-ci
+bunx @ovt2/biome-react-kit init --preset strict --no-hooks --no-ci --skip-install
+
+# Show usage
+bunx @ovt2/biome-react-kit -h
+bunx @ovt2/biome-react-kit --help
+```
+
+`init` is always safe to re-run: it never overwrites an existing
+`biome.json`/`biome.jsonc`, script, `.husky/pre-commit`, or
+`.github/workflows/biome.yml` — it just prints `!` warnings for whatever
+already exists.
+
+### `check` / `check:fix` / `ci` — run Biome without calling it directly
+
+`biome-kit` is the short alias for `@ovt2/biome-react-kit`, installed
+alongside the full name — use whichever you prefer:
+
+```sh
+# Lint/format-check the whole project
+bunx biome-kit check
+
+# Auto-fix what's fixable
+bunx biome-kit check:fix
+
+# CI-formatted output (GitHub Actions annotations), used by the generated workflow
+bunx biome-kit ci
+
+# Any of the three accept specific paths instead of defaulting to "."
+bunx biome-kit check src/
+bunx biome-kit check:fix src/components/Button.tsx
+bunx biome-kit ci src/ tests/
+```
+
+These fail with a clear message instead of a stack trace if Biome isn't
+installed yet in the current project (run `init` first).
+
+### Scripts `init` writes into your `package.json`
+
+```sh
+npm run check       # or: pnpm check / yarn check / bun run check
+npm run check:fix    # or: pnpm check:fix / yarn check:fix / bun run check:fix
+```
+
+These call the locally installed `biome` binary directly — no Bun required,
+regardless of which package manager your project uses.
+
+### Manual setup (without the CLI)
+
+```sh
+# Install Biome + the kit yourself
+bun add -d -E @biomejs/biome @ovt2/biome-react-kit
+npm install --save-dev --save-exact @biomejs/biome @ovt2/biome-react-kit
+pnpm add --save-dev --save-exact @biomejs/biome @ovt2/biome-react-kit
+yarn add --dev --exact @biomejs/biome @ovt2/biome-react-kit
+
+# Then create biome.json by hand, extending whichever preset you want:
+# { "extends": ["@ovt2/biome-react-kit/biome"] }          — base
+# { "extends": ["@ovt2/biome-react-kit/biome/strict"] }   — strict
+# { "extends": ["@ovt2/biome-react-kit/biome/next"] }     — next
+```
+
+### Manual pre-commit hook (without `init`)
+
+```sh
+bun add -d husky
+bunx husky init
+```
+
+Replace the contents of `.husky/pre-commit` with:
+
+```sh
+./node_modules/.bin/biome check --write --staged --no-errors-on-unmatched --files-ignore-unknown=true
+git update-index --again
+```
+
+Commits with unfixable errors (e.g. an unsafe-fix-only rule set to error)
+will be blocked until you resolve them.
+
+### Migrating an existing config
+
+```sh
+bunx biome migrate eslint --write
+bunx biome migrate prettier --write
+```

package/bin/cli.mjs

@@ -0,0 +1,313 @@
+#!/usr/bin/env bun
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { parseArgs } from "node:util";
+import { $ } from "bun";
+
+const KIT_DIR = join(import.meta.dir, "..");
+const KIT_PKG = await Bun.file(join(KIT_DIR, "package.json")).json();
+const KIT_NAME = KIT_PKG.name;
+const KIT_VERSION = KIT_PKG.version;
+
+const PRESET_PATHS = {
+  base: "biome",
+  strict: "biome/strict",
+  next: "biome/next",
+};
+
+const PACKAGE_MANAGERS = {
+  bun: {
+    lockfile: "bun.lock",
+    install: (pkgs) => ["bun", "add", "--dev", "--exact", ...pkgs],
+    runCheckCi: "bunx biome ci --reporter=github .",
+    setupSteps: [
+      "      - uses: oven-sh/setup-bun@v2",
+      "      - run: bun install --frozen-lockfile",
+    ],
+  },
+  npm: {
+    lockfile: "package-lock.json",
+    install: (pkgs) => ["npm", "install", "--save-dev", "--save-exact", ...pkgs],
+    runCheckCi: "npx biome ci --reporter=github .",
+    setupSteps: [
+      "      - uses: actions/setup-node@v4",
+      "        with:",
+      "          node-version: 20",
+      "          cache: npm",
+      "      - run: npm ci",
+    ],
+  },
+  pnpm: {
+    lockfile: "pnpm-lock.yaml",
+    install: (pkgs) => ["pnpm", "add", "--save-dev", "--save-exact", ...pkgs],
+    runCheckCi: "pnpm exec biome ci --reporter=github .",
+    setupSteps: [
+      "      - uses: pnpm/action-setup@v4",
+      "      - uses: actions/setup-node@v4",
+      "        with:",
+      "          node-version: 20",
+      "          cache: pnpm",
+      "      - run: pnpm install --frozen-lockfile",
+    ],
+  },
+  yarn: {
+    lockfile: "yarn.lock",
+    install: (pkgs) => ["yarn", "add", "--dev", "--exact", ...pkgs],
+    runCheckCi: "yarn biome ci --reporter=github .",
+    setupSteps: [
+      "      - uses: actions/setup-node@v4",
+      "        with:",
+      "          node-version: 20",
+      "          cache: yarn",
+      "      - run: yarn install --frozen-lockfile",
+    ],
+  },
+};
+
+const BIOME_SUBCOMMANDS = {
+  check: (paths) => ["check", ...paths],
+  "check:fix": (paths) => ["check", "--write", ...paths],
+  ci: (paths) => ["ci", "--reporter=github", ...paths],
+};
+
+const HELP = `Usage: bunx ${KIT_NAME} <command> [options]
+
+Commands:
+  init [options]   Set up Biome, scripts, hooks, and CI in the current project
+  check [paths]     Run biome check (defaults to .)
+  check:fix [paths] Run biome check --write (defaults to .)
+  ci [paths]        Run biome ci --reporter=github (defaults to .)
+
+init options:
+  --preset <base|strict|next>  Which preset to extend (default: base)
+  --no-hooks                   Skip husky + pre-commit hook setup
+  --no-ci                      Skip the GitHub Actions workflow
+  --skip-install                Print install commands instead of running them
+  -h, --help                   Show this help
+
+check / check:fix / ci run the Biome binary already installed in this
+project's node_modules — you never need to call biome yourself. The
+package manager (bun, npm, pnpm, or yarn) used by \`init\` is detected
+from the "packageManager" field in package.json or from whichever
+lockfile is present. Bun is used as the fallback when neither is found.
+
+Once installed (after \`init\`), use the shorter alias for every command
+except the first install: \`bunx biome-kit check\`, \`bunx biome-kit
+check:fix\`, \`bunx biome-kit ci\`.
+`;
+
+function fail(message) {
+  console.error(`✘ ${message}`);
+  process.exit(1);
+}
+
+function ok(message) {
+  console.log(`✔ ${message}`);
+}
+
+function warn(message) {
+  console.log(`! ${message}`);
+}
+
+function detectPackageManager(cwd, pkg) {
+  const declared = pkg.packageManager?.split("@")[0];
+  if (declared && declared in PACKAGE_MANAGERS) return declared;
+  for (const [name, pm] of Object.entries(PACKAGE_MANAGERS)) {
+    if (existsSync(join(cwd, pm.lockfile))) return name;
+  }
+  return "bun";
+}
+
+function binPath(cwd, name) {
+  return join(cwd, "node_modules", ".bin", name);
+}
+
+const { values, positionals } = parseArgs({
+  args: Bun.argv.slice(2),
+  options: {
+    preset: { type: "string", default: "base" },
+    "no-hooks": { type: "boolean", default: false },
+    "no-ci": { type: "boolean", default: false },
+    "skip-install": { type: "boolean", default: false },
+    help: { type: "boolean", short: "h", default: false },
+  },
+  allowPositionals: true,
+  strict: false,
+});
+
+if (values.help) {
+  console.log(HELP);
+  process.exit(0);
+}
+
+const command = positionals[0] ?? "init";
+const cwd = process.cwd();
+
+if (command in BIOME_SUBCOMMANDS) {
+  const biome = binPath(cwd, "biome");
+  if (!existsSync(biome)) {
+    fail(`Biome isn't installed in this project. Run: bunx ${KIT_NAME} init`);
+  }
+  const extraPaths = positionals.slice(1);
+  const biomeArgs = BIOME_SUBCOMMANDS[command](extraPaths.length ? extraPaths : ["."]);
+  try {
+    await $`${biome} ${biomeArgs}`.cwd(cwd);
+  } catch (error) {
+    process.exit(error.exitCode ?? 1);
+  }
+  process.exit(0);
+}
+
+if (command !== "init") {
+  fail(`Unknown command "${command}". Usage: bunx ${KIT_NAME} <init|check|check:fix|ci> [options]`);
+}
+
+if (!(values.preset in PRESET_PATHS)) {
+  fail(
+    `Invalid preset "${values.preset}". Valid presets: ${Object.keys(PRESET_PATHS).join(", ")}.`,
+  );
+}
+
+const pkgPath = join(cwd, "package.json");
+if (!existsSync(pkgPath)) {
+  fail("No package.json found in the current directory.");
+}
+
+const pkg = await Bun.file(pkgPath).json();
+const pmName = detectPackageManager(cwd, pkg);
+const pm = PACKAGE_MANAGERS[pmName];
+ok(`Detected package manager: ${pmName}`);
+
+const devPackages = ["@biomejs/biome", `${KIT_NAME}@${KIT_VERSION}`];
+if (!values["no-hooks"]) devPackages.push("husky");
+const installArgv = pm.install(devPackages);
+const installCmd = installArgv.join(" ");
+
+if (values["skip-install"]) {
+  warn(`Skipped install. Run: ${installCmd}`);
+} else {
+  try {
+    await $`${installArgv}`.cwd(cwd).quiet();
+    ok(`Installed ${devPackages.join(", ")}`);
+  } catch (error) {
+    fail(`Install failed: ${error.message}`);
+  }
+}
+
+const biomeJsonPath = join(cwd, "biome.json");
+const biomeJsoncPath = join(cwd, "biome.jsonc");
+const extendsSpecifier = `${KIT_NAME}/${PRESET_PATHS[values.preset]}`;
+
+if (existsSync(biomeJsonPath) || existsSync(biomeJsoncPath)) {
+  warn(`biome.json already exists — add this to its "extends": "${extendsSpecifier}"`);
+} else {
+  const config = {
+    $schema: "./node_modules/@biomejs/biome/configuration_schema.json",
+    extends: [extendsSpecifier],
+  };
+  if (values.preset === "next") {
+    config.files = { includes: ["**", "!**/.next", "!**/out", "!**/next-env.d.ts"] };
+  }
+  await Bun.write(biomeJsonPath, `${JSON.stringify(config, null, 2)}\n`);
+  ok(`Wrote biome.json (extends ${extendsSpecifier})`);
+}
+
+pkg.scripts ??= {};
+let pkgChanged = false;
+
+if (!pkg.scripts.check) {
+  pkg.scripts.check = "biome check .";
+  pkgChanged = true;
+  ok('Added script "check"');
+} else {
+  warn('Script "check" already exists — left untouched');
+}
+
+if (!pkg.scripts["check:fix"]) {
+  pkg.scripts["check:fix"] = "biome check --write .";
+  pkgChanged = true;
+  ok('Added script "check:fix"');
+} else {
+  warn('Script "check:fix" already exists — left untouched');
+}
+
+if (!values["no-hooks"]) {
+  if (!pkg.scripts.prepare) {
+    pkg.scripts.prepare = "husky";
+    pkgChanged = true;
+    ok('Added script "prepare"');
+  } else if (!pkg.scripts.prepare.includes("husky")) {
+    pkg.scripts.prepare = `${pkg.scripts.prepare} && husky`;
+    pkgChanged = true;
+    ok('Appended husky to existing "prepare" script');
+  } else {
+    warn('Script "prepare" already runs husky — left untouched');
+  }
+}
+
+if (pkgChanged) {
+  await Bun.write(pkgPath, `${JSON.stringify(pkg, null, 2)}\n`);
+}
+
+if (!values["no-hooks"]) {
+  const gitDir = join(cwd, ".git");
+  if (!existsSync(gitDir)) {
+    warn("No .git directory found — skipping husky hook setup");
+  } else {
+    const huskyDir = join(cwd, ".husky");
+    const hookPath = join(huskyDir, "pre-commit");
+    if (existsSync(hookPath)) {
+      warn(".husky/pre-commit already exists — left untouched");
+    } else {
+      await $`mkdir -p ${huskyDir}`.quiet();
+      await Bun.write(hookPath, await Bun.file(join(KIT_DIR, "templates", "pre-commit")).text());
+      await $`chmod 755 ${hookPath}`.quiet();
+      ok("Wrote .husky/pre-commit");
+      if (values["skip-install"]) {
+        warn("Skipped: run `node_modules/.bin/husky` to finish git hooks setup");
+      } else {
+        const husky = binPath(cwd, "husky");
+        if (existsSync(husky)) {
+          try {
+            await $`${husky}`.cwd(cwd).quiet();
+            ok("Ran husky");
+          } catch (error) {
+            warn(`husky failed: ${error.message}`);
+          }
+        } else {
+          warn(`husky binary not found at ${husky} — run it manually once installed`);
+        }
+      }
+    }
+  }
+}
+
+if (!values["no-ci"]) {
+  const workflowsDir = join(cwd, ".github", "workflows");
+  const ciPath = join(workflowsDir, "biome.yml");
+  if (existsSync(ciPath)) {
+    warn(".github/workflows/biome.yml already exists — left untouched");
+  } else {
+    const workflow = `name: Biome
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+jobs:
+  biome:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+${pm.setupSteps.join("\n")}
+      - run: ${pm.runCheckCi}
+`;
+    await $`mkdir -p ${workflowsDir}`.quiet();
+    await Bun.write(ciPath, workflow);
+    ok("Wrote .github/workflows/biome.yml");
+  }
+}
+
+console.log(`\nRun: ${pmName} run check:fix`);

package/package.json

@@ -1,6 +1,46 @@
 {
   "name": "@ovt2/biome-react-kit",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "2.3.0",
+  "description": "Shared Biome lint/format/check preset for React apps",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "biome-react-kit": "bin/cli.mjs",
+    "biome-kit": "bin/cli.mjs"
+  },
+  "exports": {
+    "./biome": "./presets/base.json",
+    "./biome/strict": "./presets/strict.json",
+    "./biome/next": "./presets/next.json",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "bin",
+    "presets",
+    "templates",
+    "README.md"
+  ],
+  "scripts": {
+    "check": "biome check .",
+    "check:fix": "biome check --write ."
+  },
+  "peerDependencies": {
+    "@biomejs/biome": ">=2.2.0 <3"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.6.4"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "bun": ">=1.2"
+  },
+  "keywords": [
+    "biome",
+    "react",
+    "lint",
+    "format"
+  ],
+  "author": "Expo2Dev"
+}

package/presets/base.json

@@ -0,0 +1,45 @@
+{
+  "$schema": "https://biomejs.dev/schemas/2.6.4/schema.json",
+  "vcs": {
+    "enabled": true,
+    "clientKind": "git",
+    "useIgnoreFile": true
+  },
+  "formatter": {
+    "enabled": true,
+    "indentStyle": "space",
+    "indentWidth": 2,
+    "lineWidth": 100
+  },
+  "javascript": {
+    "formatter": {
+      "quoteStyle": "double",
+      "semicolons": "always",
+      "trailingCommas": "all"
+    }
+  },
+  "assist": {
+    "actions": {
+      "source": { "organizeImports": "on" }
+    }
+  },
+  "linter": {
+    "enabled": true,
+    "domains": {
+      "react": "recommended"
+    },
+    "rules": {
+      "preset": "recommended",
+      "correctness": {
+        "noUnusedImports": "warn",
+        "noUnusedVariables": "warn"
+      },
+      "suspicious": {
+        "noConsole": {
+          "level": "warn",
+          "options": { "allow": ["error", "warn"] }
+        }
+      }
+    }
+  }
+}

package/presets/next.json

@@ -0,0 +1,10 @@
+{
+  "$schema": "https://biomejs.dev/schemas/2.6.4/schema.json",
+  "extends": ["./base.json"],
+  "linter": {
+    "domains": {
+      "react": "recommended",
+      "next": "recommended"
+    }
+  }
+}

package/presets/strict.json

@@ -0,0 +1,23 @@
+{
+  "$schema": "https://biomejs.dev/schemas/2.6.4/schema.json",
+  "extends": ["./base.json"],
+  "linter": {
+    "rules": {
+      "correctness": {
+        "noUnusedImports": "error",
+        "noUnusedVariables": "error",
+        "useExhaustiveDependencies": "error"
+      },
+      "suspicious": {
+        "noExplicitAny": "error",
+        "noConsole": {
+          "level": "error",
+          "options": { "allow": ["error", "warn"] }
+        }
+      },
+      "style": {
+        "noNonNullAssertion": "error"
+      }
+    }
+  }
+}

package/templates/pre-commit

@@ -0,0 +1,2 @@
+./node_modules/.bin/biome check --write --staged --no-errors-on-unmatched --files-ignore-unknown=true
+git update-index --again