@ovt2/biome-react-kit 2.1.0 → 2.3.0

package/README.md

@@ -34,17 +34,34 @@ 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.
 
-### Manual setup
+## 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
-bun add -d -E @biomejs/biome @ovt2/biome-react-kit
+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
 ```
 
-Create `biome.json`:
+(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.)
 
-```json
-{ "extends": ["@ovt2/biome-react-kit/biome"] }
-```
+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
 
@@ -72,10 +89,94 @@ Add scripts:
 "check:fix": "biome check --write ."
 ```
 
-## Pre-commit hook
+## 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
+```
 
-Run Biome on staged files before every commit so formatting and fixable lint
-issues never reach the repo:
+### Manual pre-commit hook (without `init`)
 
 ```sh
 bun add -d husky
@@ -92,7 +193,7 @@ 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 from ESLint/Prettier
+### Migrating an existing config
 
 ```sh
 bunx biome migrate eslint --write

package/bin/cli.mjs

@@ -64,19 +64,36 @@ const PACKAGE_MANAGERS = {
   },
 };
 
-const HELP = `Usage: bunx ${KIT_NAME} init [options]
+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]
 
-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
 
-The package manager (bun, npm, pnpm, or yarn) is detected from the
-"packageManager" field in package.json or from whichever lockfile is
-present in the current directory. Bun is used as the fallback when
-neither is found.
+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) {
@@ -124,8 +141,25 @@ if (values.help) {
 }
 
 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 [options]`);
+  fail(`Unknown command "${command}". Usage: bunx ${KIT_NAME} <init|check|check:fix|ci> [options]`);
 }
 
 if (!(values.preset in PRESET_PATHS)) {
@@ -134,7 +168,6 @@ if (!(values.preset in PRESET_PATHS)) {
   );
 }
 
-const cwd = process.cwd();
 const pkgPath = join(cwd, "package.json");
 if (!existsSync(pkgPath)) {
   fail("No package.json found in the current directory.");

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "@ovt2/biome-react-kit",
-  "version": "2.1.0",
+  "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-react-kit": "bin/cli.mjs",
+    "biome-kit": "bin/cli.mjs"
   },
   "exports": {
     "./biome": "./presets/base.json",