@prb/devkit 1.0.0

package/.prettierrc.js

@@ -0,0 +1,13 @@
+/** @type {import("prettier").Config} */
+export default {
+  printWidth: 120,
+  trailingComma: "all",
+  overrides: [
+    {
+      files: "*.md",
+      options: {
+        proseWrap: "always",
+      },
+    },
+  ],
+};

package/.prettierrc.json

@@ -0,0 +1,13 @@
+{
+  "$schema": "https://json.schemastore.org/prettierrc",
+  "printWidth": 120,
+  "trailingComma": "all",
+  "overrides": [
+    {
+      "files": "*.md",
+      "options": {
+        "proseWrap": "always"
+      }
+    }
+  ]
+}

package/LICENSE.md

@@ -0,0 +1,16 @@
+MIT License
+
+Copyright (c) 2025 Paul Razvan Berg
+
+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

@@ -0,0 +1,157 @@
+# 🛠️ Devkit
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![npm](https://img.shields.io/npm/v/@prb/devkit)](https://www.npmjs.com/package/@prb/devkit)
+
+Personal configuration files and reusable scripts. Designed to be extended and customized as needed.
+
+## 📦 Installation
+
+```bash
+npm install @prb/devkit
+```
+
+Or with other package managers:
+
+```bash
+pnpm add @prb/devkit
+bun add @prb/devkit
+```
+
+## 🚀 Usage
+
+### Biome
+
+Extend the base Biome configuration in your `biome.jsonc`:
+
+```jsonc
+{
+  "$schema": "https://biomejs.dev/schemas/latest/schema.json",
+  "extends": ["@prb/devkit/biome"],
+}
+```
+
+For UI projects, use the UI variant:
+
+```jsonc
+{
+  "extends": ["@prb/devkit/biome/ui"],
+}
+```
+
+### Prettier
+
+Reference the Prettier config in your `package.json`:
+
+```json
+{
+  "prettier": "@prb/devkit/prettier"
+}
+```
+
+### TypeScript
+
+Extend TSConfig presets in your `tsconfig.json`:
+
+```json
+{
+  "extends": "@prb/devkit/tsconfig/base"
+}
+```
+
+Available presets:
+
+- `@prb/devkit/tsconfig/base` — Base TypeScript configuration
+- `@prb/devkit/tsconfig/build` — Build-optimized configuration
+- `@prb/devkit/tsconfig/next` — Next.js configuration
+
+### Vitest
+
+Use the devkit vitest config factory in your `vitest.config.ts`:
+
+```typescript
+import { defineDevkitConfig } from "@prb/devkit/vitest";
+
+export default defineDevkitConfig({
+  environment: "jsdom", // or "node" (default), "happy-dom"
+  setupFiles: ["./tests/setup.ts"],
+  coverage: true,
+});
+```
+
+The config provides CI-aware defaults:
+
+- `globals: true`
+- `retry: 2` in CI, `0` locally
+- `testTimeout: 30s` in CI, `10s` locally
+- `reporters: ["basic"]` in CI, `["verbose"]` locally
+
+For merging with existing Vite configs:
+
+```typescript
+import { defineDevkitConfig, mergeConfig } from "@prb/devkit/vitest";
+import { defineConfig } from "vitest/config";
+
+export default mergeConfig(
+  defineDevkitConfig({ environment: "jsdom" }),
+  defineConfig({
+    test: {
+      alias: { "@": "./src" },
+    },
+  }),
+);
+```
+
+### Just
+
+Import Just recipes in your `justfile`:
+
+```just
+import "@prb/devkit/just/base.just"
+import "@prb/devkit/just/npm.just"
+```
+
+Available modules:
+
+| Module          | Description                     |
+| --------------- | ------------------------------- |
+| `base.just`     | Common development recipes      |
+| `csv.just`      | CSV/TSV validation with qsv     |
+| `npm.just`      | NPM package management          |
+| `settings.just` | Just settings and configuration |
+| `vercel.just`   | Vercel build and deploy         |
+
+## ⚙️ Available Configs
+
+| Tool        | Config File/Directory                    |
+| ----------- | ---------------------------------------- |
+| 🔍 Biome    | [`biome/`](./biome/)                     |
+| 🛠 Just     | [`just/`](./just/)                       |
+| ✨ Prettier | [`.prettierrc.json`](./.prettierrc.json) |
+| 📦 TSConfig | [`tsconfig/`](./tsconfig/)               |
+| 🧪 Vitest   | [`vitest/`](./vitest/)                   |
+| 💻 VSCode   | [`vscode/`](./vscode/)                   |
+
+## 🐈‍⬛ GitHub Actions
+
+Reusable composite actions for GitHub CI workflows.
+
+| Action                                        | Description                                |
+| --------------------------------------------- | ------------------------------------------ |
+| [`actions/setup`](./actions/setup/)           | Install dependencies (Node.js, Just, etc.) |
+| [`actions/node-cache`](./actions/node-cache/) | Cache Node.js dependencies                 |
+
+```yaml
+- uses: PaulRBerg/devkit/actions/setup@v1
+```
+
+Dependency caching stores only the package-manager cache, not `node_modules`. Set `save-cache: true` in at most one
+parallel job to publish a refreshed cache.
+
+## 🤝 Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## 📄 License
+
+This project is licensed under MIT — see the [LICENSE](LICENSE.md) file for details.

package/biome/base.jsonc

@@ -0,0 +1,123 @@
+// Devkit configuration for Biome v2: https://next.biomejs.dev
+//
+// This is a shared base configuration meant to be extended in consuming projects.
+//
+// IMPORTANT: Consumers must add their own `files.includes` patterns to specify
+// which files to lint and format. For example:
+//
+//   {
+//     "extends": ["@prb/devkit/biome/base"],
+//     "files": {
+//       "includes": ["**/*.{css,js,jsx,json,ts,tsx}", "!node_modules"]
+//     }
+//   }
+//
+// You may also add override blocks with custom `includes` patterns for
+// granular rule customization.
+{
+  "$schema": "https://biomejs.dev/schemas/latest/schema.json",
+  "assist": {
+    "enabled": true,
+    "actions": {
+      "source": {
+        "organizeImports": "on",
+        "useSortedKeys": {
+          "level": "on",
+          "options": {
+            "groupByNesting": true
+          }
+        }
+      }
+    }
+  },
+  "files": {
+    "maxSize": 5242880 // 5MB
+  },
+  "formatter": {
+    "enabled": true,
+    "formatWithErrors": true,
+    "indentStyle": "space",
+    "lineWidth": 100
+  },
+  // Needed to override ultracite
+  "json": {
+    "formatter": {
+      "lineWidth": 100
+    }
+  },
+  "linter": {
+    "enabled": true,
+    "rules": {
+      "preset": "recommended",
+      "complexity": {
+        "noImplicitCoercions": "error", // forbid `!!foo`, allow `Boolean(foo)`
+        "noVoid": "off", // void is useful in some cases e.g. `useEffect` callbacks
+        "useSimplifiedLogicExpression": "off", // the rule is cool but it gets agents stuck
+        "noUselessUndefined": "off" // we want explicit undefined return values
+      },
+      "correctness": {
+        "noUnusedImports": "off", // allow unused imports during development
+        "noUnusedVariables": "error"
+      },
+      "nursery": {
+        "noFloatingPromises": "error" // floating promises can lead to bugs
+      },
+      "performance": {
+        "noBarrelFile": "off", // barrel exports lead to cleaner imports
+        "noDelete": "off", // disabled due to https://github.com/biomejs/biome/issues/4093
+        "noNamespaceImport": "off" // namespaces are cool
+      },
+      "style": {
+        "noEnum": "off", // enums are useful in some cases e.g. UI states
+        "noNamespace": "off", // namespaces are cool
+        "useBlockStatements": "off", // turned off because it gets AIs stuck
+        "useDefaultSwitchClause": "off", // already handled by TypeScript
+        "useTemplate": "off", // allow string concatenation using `+`
+        "useConsistentTypeDefinitions": {
+          "level": "warn",
+          "options": {
+            "style": "type"
+          }
+        },
+        "useFilenamingConvention": {
+          "level": "error",
+          "options": {
+            "filenameCases": ["kebab-case", "camelCase", "PascalCase", "export"]
+          }
+        },
+        // disabled due to https://github.com/biomejs/biome/issues/8450
+        "useImportType": {
+          "level": "warn",
+          "options": {
+            "style": "separatedType"
+          }
+        }
+      }
+    }
+  },
+  "overrides": [
+    {
+      // Disabling sorted keys because ordering is often important in JSON files
+      "includes": ["**/*.{json,json5,jsonc}"],
+      "assist": {
+        "actions": {
+          "source": {
+            "useSortedKeys": "off"
+          }
+        }
+      },
+      // Needed to override ultracite
+      "json": {
+        "parser": {
+          "allowComments": true,
+          "allowTrailingCommas": true
+        }
+      }
+    }
+  ],
+  "vcs": {
+    "clientKind": "git",
+    "enabled": true,
+    "useIgnoreFile": true
+  }
+}

package/biome/ui.jsonc

@@ -0,0 +1,80 @@
+// Devkit UI configuration for Biome v2
+//
+// Extends base configuration with UI-specific rules for accessibility,
+// Tailwind CSS class sorting, and CSS modules support.
+//
+// IMPORTANT: Consumers must extend BOTH configs and add their own
+// `files.includes` patterns. For example:
+//
+//   {
+//     "extends": ["@prb/devkit/biome/base", "@prb/devkit/biome/ui"],
+//     "files": {
+//       "includes": ["**/*.{css,js,jsx,json,ts,tsx}", "!node_modules"]
+//     }
+//   }
+{
+  "$schema": "https://biomejs.dev/schemas/latest/schema.json",
+  "assist": {
+    "enabled": true,
+    "actions": {
+      "source": {
+        "noDuplicateClasses": "on",
+        "useSortedAttributes": "on"
+      }
+    }
+  },
+  "css": {
+    "formatter": {
+      "lineWidth": 100
+    },
+    "parser": {
+      "cssModules": true,
+      "tailwindDirectives": true
+    }
+  },
+  "linter": {
+    "rules": {
+      "a11y": {
+        "noSvgWithoutTitle": "off",
+        "useKeyWithClickEvents": "off"
+      },
+      "correctness": {
+        "useExhaustiveDependencies": "off" // doesn't work with React Compiler: https://github.com/biomejs/biome/issues/5293
+      },
+      "nursery": {
+        // Tailwind class ordering is handled by ESLint (better-tailwindcss/enforce-consistent-class-order).
+        // Biome's useSortedClasses lacks a Tailwind v4 sort preset and sorts text-* utilities alphabetically,
+        // interleaving font-size (text-sm) with color (text-red-500) utilities.
+        // Tracked upstream: https://github.com/biomejs/biome/issues/1274
+        "useSortedClasses": "off"
+      },
+      "style": {
+        // Promoted out of nursery in Biome 2.5.0.
+        "useErrorCause": "error"
+      },
+      "suspicious": {
+        "noConsole": {
+          "level": "warn",
+          "options": {
+            // console.error allowed for error boundaries and critical failures
+            "allow": ["error"]
+          }
+        }
+      }
+    }
+  },
+  "overrides": [
+    // ── Styles files ─────────────────────────────────────────────────────────
+    // Disable alphabetical sorting in styles files, where order is important for CSS
+    {
+      "includes": ["**/*.styles.ts"],
+      "assist": {
+        "actions": {
+          "source": {
+            "useSortedKeys": "off"
+          }
+        }
+      }
+    }
+  ]
+}

package/just/_vercel_helpers.py

@@ -0,0 +1,85 @@
+"""Shared helpers for Vercel Just recipes."""
+
+import json
+import os
+import subprocess
+import sys
+
+
+def run(*cmd):
+    """Run a command, exiting on failure."""
+    result = subprocess.run(cmd)
+    if result.returncode != 0:
+        sys.exit(result.returncode)
+
+
+def run_capture_url(*cmd) -> str:
+    """Run a command, tee its stdout to the user, and return the last non-empty stdout line.
+
+    Used to capture the deployment URL printed by `vercel deploy` while still streaming
+    its output to the caller. Exits on non-zero return codes, mirroring `run`.
+    """
+    proc = subprocess.Popen(cmd, stdout=subprocess.PIPE, text=True, bufsize=1)
+    assert proc.stdout is not None
+    last = ""
+    for line in proc.stdout:
+        sys.stdout.write(line)
+        sys.stdout.flush()
+        stripped = line.strip()
+        if stripped:
+            last = stripped
+    proc.wait()
+    if proc.returncode != 0:
+        sys.exit(proc.returncode)
+    return last
+
+
+def emit_deployment_url(url: str) -> None:
+    """Publish the deployment URL to GitHub Actions and/or a caller-specified file.
+
+    - If `GITHUB_OUTPUT` is set, appends `deployment_url=<url>` so workflow steps can read it
+      via `steps.<id>.outputs.deployment_url`.
+    - If `VERCEL_DEPLOYMENT_URL_FILE` is set, writes the URL to that path (useful for local
+      scripts and non-GitHub CI systems).
+    - Always prints a human-readable `Deployment URL: <url>` line to stdout.
+    """
+    github_output = os.environ.get("GITHUB_OUTPUT")
+    if github_output:
+        with open(github_output, "a", encoding="utf-8") as fh:
+            fh.write(f"deployment_url={url}\n")
+
+    url_file = os.environ.get("VERCEL_DEPLOYMENT_URL_FILE")
+    if url_file:
+        with open(url_file, "w", encoding="utf-8") as fh:
+            fh.write(url)
+
+    print(f"\nDeployment URL: {url}")
+
+
+def resolve_vercel_env(app, project_ids_json):
+    """Resolve VERCEL_PROJECT_ID and VERCEL_TOKEN, setting them in os.environ.
+
+    Precedence for project ID:
+      1. VERCEL_PROJECT_ID already set in the environment
+      2. Lookup `app` in the VERCEL_PROJECT_IDS JSON map
+
+    Returns (project_id, token).
+    """
+    project_id = os.environ.get("VERCEL_PROJECT_ID", "")
+    if not project_id:
+        project_ids = json.loads(project_ids_json)
+        if app not in project_ids:
+            print(
+                f"Error: unknown app '{app}'. Known apps: {', '.join(project_ids) or '(none)'}",
+                file=sys.stderr,
+            )
+            sys.exit(1)
+        project_id = project_ids[app]
+    os.environ["VERCEL_PROJECT_ID"] = project_id
+
+    token = os.environ.get("VERCEL_TOKEN", "")
+    if not token:
+        print("Error: VERCEL_TOKEN is not set.", file=sys.stderr)
+        sys.exit(1)
+
+    return project_id, token

package/just/base.just

@@ -0,0 +1,146 @@
+import "./settings.just"
+import "./utils.just"
+
+# ---------------------------------------------------------------------------- #
+#                                 DEPENDENCIES                                 #
+# ---------------------------------------------------------------------------- #
+
+# Ni: https://github.com/antfu-collective/ni
+na := require("na")
+ni := require("ni")
+nlx := require("nlx")
+
+# ---------------------------------------------------------------------------- #
+#                                   CONSTANTS                                  #
+# ---------------------------------------------------------------------------- #
+
+GLOBS_PRETTIER := "\"**/*.{md,mdx,yaml,yml}\""
+
+# ---------------------------------------------------------------------------- #
+#                                    RECIPES                                   #
+# ---------------------------------------------------------------------------- #
+
+# Clean files
+[no-cd]
+clean:
+    just _clean ".DS_Store"
+
+[no-cd]
+_clean +globs:
+    nlx del-cli "{{ globs }}"
+
+# Clear node_modules recursively
+[confirm("Are you sure you want to delete all node_modules, including in subdirectories? [y/N]"), no-cd]
+@clean-modules +globs="**/node_modules":
+    echo "🧹 Deleting node_modules recursively..."
+    nlx del-cli --verbose {{ globs }}
+
+# Install the Node.js dependencies; run with --frozen to install the dependencies with the frozen lockfile
+[no-cd]
+@install *args:
+    ni {{ args }}
+
+# Build with TypeScript
+[no-cd]
+[arg("project", long, short="p", help="Path to tsconfig.json")]
+@tsc-build project="tsconfig.json":
+    na tsc -p {{ project }}
+alias tb := tsc-build
+
+# ---------------------------------------------------------------------------- #
+#                                    CHECKS                                    #
+# ---------------------------------------------------------------------------- #
+
+# Check code with Biome - runs both the checker and the linter
+[group("checks"), no-cd]
+@biome-check +globs=".":
+    na biome check {{ globs }}
+alias bc := biome-check
+
+# Lint code with Biome
+[group("checks"), no-cd]
+@biome-lint +globs=".":
+    na biome lint {{ globs }}
+alias bl := biome-lint
+
+# Fix code with Biome
+# The `noUnusedImports` rule is disabled by default to allow unused imports during development
+[group("checks"), no-cd]
+@biome-write +globs=".":
+    na biome check --write {{ globs }}
+    na biome lint --unsafe --write --only correctness/noUnusedImports {{ globs }}
+alias bw := biome-write
+
+# Run all code checks
+[group("checks"), no-cd]
+@_full-check:
+    just _run-with-status biome-check
+    just _run-with-status prettier-check
+    just _run-with-status type-check
+
+# Run all code checks
+[group("checks"), no-cd]
+@full-check: _full-check
+    echo ""
+    echo '{{ GREEN }}All code checks passed!{{ NORMAL }}'
+alias fc := full-check
+
+# Run all code fixes
+[group("checks"), no-cd]
+@_full-write:
+    just _run-with-status biome-write
+    just _run-with-status prettier-write
+
+# Run all code fixes
+[group("checks"), no-cd]
+@full-write: _full-write
+    echo ""
+    echo '{{ GREEN }}All code fixes applied!{{ NORMAL }}'
+alias fw := full-write
+
+# Run knip checks
+[group("checks"), no-cd]
+@knip-check:
+    na knip
+alias kc := knip-check
+
+# Run knip fix
+[group("checks"), no-cd]
+@knip-write:
+    na knip --fix
+alias kw := knip-write
+
+# Check Prettier formatting
+[group("checks"), no-cd]
+@prettier-check +globs=GLOBS_PRETTIER:
+    na prettier \
+        --check \
+        --cache \
+        --log-level warn \
+        --no-error-on-unmatched-pattern \
+        {{ globs }}
+alias pc := prettier-check
+
+# Format using Prettier
+[group("checks"), no-cd]
+@prettier-write +globs=GLOBS_PRETTIER:
+    na prettier \
+        --write \
+        --cache \
+        --log-level warn \
+        --no-error-on-unmatched-pattern \
+        {{ globs }}
+alias pw := prettier-write
+
+# Type check with TypeScript (tsgo default, falls back to tsc if unavailable)
+[group("checks"), no-cd, script("bash")]
+[arg("compiler", long, short="c", help="TypeScript compiler (tsgo or tsc)")]
+[arg("project", long, short="p", help="Path to tsconfig.json")]
+type-check compiler="tsgo" project="tsconfig.json":
+    cmd="{{ compiler }}"
+    if [[ "$cmd" == "tsgo" ]] && [[ ! -x "node_modules/.bin/tsgo" ]]; then
+        cmd="tsc"
+    fi
+    na "$cmd" --noEmit --project {{ project }}
+alias tc := type-check
+alias tsc-check := type-check

package/just/csv.just

@@ -0,0 +1,126 @@
+import "./settings.just"
+
+# ---------------------------------------------------------------------------- #
+#                                    SCRIPTS                                   #
+# ---------------------------------------------------------------------------- #
+
+# Check CSV/TSV files using qsv: https://github.com/dathere/qsv
+[group("checks"), script("python3")]
+[arg("glob", long, short="g", help="Glob pattern for CSV/TSV files")]
+[arg("schema", long, short="s", help="JSON schema file for validation")]
+[arg("ignore", long, short="x", help="Space-separated ignore patterns")]
+_csv-check glob="data/*/*.{csv,tsv}" schema="" ignore="*.invalid *.valid *validation-errors.*":
+    import fnmatch
+    import glob as globmod
+    import re
+    import subprocess
+    import sys
+
+    def expand_braces(pattern):
+        """Expand brace patterns like {a,b} into multiple patterns."""
+        match = re.search(r'\{([^}]+)\}', pattern)
+        if not match:
+            return [pattern]
+        prefix, suffix = pattern[:match.start()], pattern[match.end():]
+        return [p for opt in match.group(1).split(',') for p in expand_braces(prefix + opt + suffix)]
+
+    # Check qsv is available
+    if subprocess.run(["which", "qsv"], capture_output=True).returncode != 0:
+        print("✗ qsv CLI not found")
+        print("Install it: https://github.com/dathere/qsv")
+        sys.exit(1)
+
+    ignore_patterns = "{{ ignore }}".split() if "{{ ignore }}" else []
+    schema = "{{ schema }}" or None
+    globs = "{{ glob }}"
+
+    # Infer extension label from glob pattern
+    ext_match = re.search(r'\.(\w+|\{[^}]+\})$', globs)
+    if ext_match:
+        ext = ext_match.group(1)
+        if ext.startswith('{') and ext.endswith('}'):
+            # Handle brace expansion like {csv,tsv}
+            ext_label = '.' + '/'.join(f'.{e}' for e in ext[1:-1].split(','))[1:]
+        else:
+            ext_label = f'.{ext}'
+    else:
+        ext_label = 'CSV/TSV'
+
+    print(f"Validating {ext_label} files...")
+    files = [f for pattern in expand_braces(globs) for f in globmod.glob(pattern, recursive=True)]
+
+    # Filter ignored files
+    files = [f for f in files if not any(fnmatch.fnmatch(f, p) for p in ignore_patterns)]
+
+    if not files:
+        print(f"ℹ️  No {ext_label} files found to validate")
+        sys.exit(0)
+
+    for file in files:
+        cmd = ["qsv", "validate", file]
+        if schema:
+            cmd.append(schema)
+        result = subprocess.run(cmd, capture_output=True)
+        if result.returncode != 0:
+            print(f"❌ Validation failed for: {file}")
+            subprocess.run(["just", "_csv-show-errors", file])
+            sys.exit(1)
+
+    print(f"✅ All {ext_label} files are valid")
+
+# Show validation errors for a CSV/TSV file
+[group("checks"), script("python3")]
+_csv-show-errors file:
+    import os
+    import subprocess
+    import sys
+
+    file = "{{ file }}"
+    # qsv always produces .validation-errors.tsv regardless of input format
+    error_file = f"{file}.validation-errors.tsv"
+
+    if not os.path.exists(error_file):
+        print(f"Error file not found: {error_file}")
+        sys.exit(0)
+
+    # Count errors (qsv auto-detects delimiter based on file extension)
+    result = subprocess.run(["qsv", "count", error_file], capture_output=True, text=True)
+    try:
+        total = int(result.stdout.strip()) if result.returncode == 0 and result.stdout.strip() else 0
+    except ValueError:
+        total = 0
+
+    print()
+    if total > 0:
+        print(f"First 20 validation errors ({total} total):")
+    else:
+        print("Validation errors:")
+    print()
+
+    # Try qsv table for nice formatting, fall back to reading file directly
+    slice_result = subprocess.run(
+        ["qsv", "slice", "--start", "0", "--len", "21", error_file],
+        capture_output=True, text=True
+    )
+    if slice_result.returncode == 0:
+        table_result = subprocess.run(
+            ["qsv", "table"],
+            input=slice_result.stdout,
+            capture_output=True, text=True
+        )
+        if table_result.returncode == 0:
+            print(table_result.stdout)
+        else:
+            print(slice_result.stdout)
+    else:
+        with open(error_file) as f:
+            for i, line in enumerate(f):
+                if i >= 21:
+                    break
+                print(line, end="")
+
+    if total > 20:
+        print()
+        print(f"... and {total - 20} more errors")
+    print()
+    print(f"Full details: {error_file}")

package/just/npm.just

@@ -0,0 +1,54 @@
+import "./settings.just"
+
+# ---------------------------------------------------------------------------- #
+#                                 DEPENDENCIES                                 #
+# ---------------------------------------------------------------------------- #
+
+# Jq
+jq := require("jq")
+
+# Npm
+npm := require("npm")
+
+# ---------------------------------------------------------------------------- #
+#                                    SCRIPTS                                   #
+# ---------------------------------------------------------------------------- #
+
+# Publish the npm package, e.g. v1.0.0
+[group("publish")]
+[arg("tag", long, value="true")]
+publish tag="false" *args:
+  npm publish {{ args }}
+  @{{ if tag == "true" { "just tag $(jq -r '.version' package.json)" } else { "true" } }}
+
+# Publish using the `beta` tag, e.g. v1.0.0-beta.1
+[group("publish")]
+publish-beta *args:
+  @just check-beta-version
+  npm publish --tag beta {{ args }}
+
+# Tag the new version
+[group("publish")]
+tag *version:
+  git tag -am "{{ version }}" {{ version }}
+  git push origin --tags
+
+# ---------------------------------------------------------------------------- #
+#                                PRIVATE HELPERS                               #
+# ---------------------------------------------------------------------------- #
+
+
+# Check that package.json version includes -beta.x suffix
+[private, script("bash")]
+@check-beta-version:
+  # Extract version from package.json using jq for reliable JSON parsing
+  version=$(jq -r '.version' package.json)
+
+  # Check if version contains -beta suffix
+  if [[ "$version" =~ -beta\.[0-9]+$ ]]; then
+    echo "✓ Version $version includes beta suffix"
+  else
+    echo "✗ Error: Version $version does not include -beta.x suffix"
+    echo "Please update package.json version to include -beta.x (e.g., 1.0.0-beta.1)"
+    exit 1
+  fi

package/just/settings.just

@@ -0,0 +1,6 @@
+# See https://just.systems/man/en/settings.html
+set allow-duplicate-recipes
+set allow-duplicate-variables
+set lists
+set shell := ["bash", "-euo", "pipefail", "-c"]
+set unstable

package/just/utils.just

@@ -0,0 +1,15 @@
+import "./settings.just"
+
+# ---------------------------------------------------------------------------- #
+#                                   UTILITIES                                  #
+# ---------------------------------------------------------------------------- #
+
+# Private recipe to run a check with formatted output
+[no-cd]
+@_run-with-status recipe *args:
+    echo ""
+    echo '{{ CYAN }}→ Running {{ recipe }}...{{ NORMAL }}'
+    just {{ recipe }} {{ args }}
+    echo '{{ GREEN }}✓ {{ recipe }} completed{{ NORMAL }}'
+alias rws := _run-with-status
+alias _rws := _run-with-status

package/just/vercel.just

@@ -0,0 +1,86 @@
+import "./settings.just"
+
+# ---------------------------------------------------------------------------- #
+#                                 DEPENDENCIES                                 #
+# ---------------------------------------------------------------------------- #
+
+# Ni: https://github.com/antfu-collective/ni
+na := require("na")
+
+# ---------------------------------------------------------------------------- #
+#                                   CONSTANTS                                  #
+# ---------------------------------------------------------------------------- #
+
+# Consumer MUST override with a JSON map of app name → Vercel project ID.
+# Example: '{"portal": "prj_xxx", "landing": "prj_yyy"}'
+# Note: if VERCEL_PROJECT_ID is already set in the environment, this map is ignored.
+VERCEL_PROJECT_IDS := '{}'
+
+# ---------------------------------------------------------------------------- #
+#                                    RECIPES                                   #
+# ---------------------------------------------------------------------------- #
+
+# Build website for Vercel deployment
+[arg("app", long)]
+[arg("env", long)]
+[group("vercel")]
+build app env="staging":
+    @just _vercel-build "{{ app }}" "{{ env }}"
+alias vb := build
+
+# Deploy website to Vercel. Trailing args are forwarded to `vercel deploy`.
+[arg("app", long)]
+[arg("env", long)]
+[arg("skip_build", long="skip-build", value="true")]
+[confirm("Are you sure you want to deploy? [y/N]")]
+[group("vercel")]
+deploy app env="staging" skip_build="false" *args="":
+    @just _vercel-deploy "{{ app }}" "{{ env }}" "{{ skip_build }}" {{ args }}
+alias vd := deploy
+
+# ---------------------------------------------------------------------------- #
+#                                PRIVATE HELPERS                               #
+# ---------------------------------------------------------------------------- #
+
+# Core build: vercel pull + vercel build
+[private, script("python3")]
+_vercel-build app env:
+    import sys; sys.path.insert(0, "{{ source_directory() }}")
+    import os
+    from _vercel_helpers import resolve_vercel_env, run
+
+    # Workaround for https://github.com/vercel/vercel/issues/14666
+    os.environ["VERCEL_TARGET_ENV"] = "{{ env }}"
+    os.environ["NEXT_PUBLIC_VERCEL_TARGET_ENV"] = "{{ env }}"
+
+    project_id, token = resolve_vercel_env("{{ app }}", '{{ VERCEL_PROJECT_IDS }}')
+
+    # Pull the environment from the Vercel project
+    run("na", "vercel", "pull", "--environment={{ env }}", f"--token={token}", "--yes")
+
+    # Build the project
+    run("na", "vercel", "build", "--target={{ env }}", f"--token={token}")
+
+# Core deploy: optionally build, then deploy prebuilt artifacts
+[private, script("python3")]
+_vercel-deploy app env skip_build="false" *args="":
+    import shlex, sys; sys.path.insert(0, "{{ source_directory() }}")
+    import os
+    from _vercel_helpers import emit_deployment_url, resolve_vercel_env, run, run_capture_url
+
+    # Build the project if not skipped (calls the PUBLIC recipe so consumer overrides apply)
+    if "{{ skip_build }}" != "true":
+        run("just", "build", "--app={{ app }}", "--env={{ env }}")
+
+    # Workaround for https://github.com/vercel/vercel/issues/14666
+    os.environ["VERCEL_TARGET_ENV"] = "{{ env }}"
+    os.environ["NEXT_PUBLIC_VERCEL_TARGET_ENV"] = "{{ env }}"
+
+    project_id, token = resolve_vercel_env("{{ app }}", '{{ VERCEL_PROJECT_IDS }}')
+
+    # Deploy the project to Vercel, capturing the deployment URL from stdout
+    extra = shlex.split("""{{ args }}""")
+    url = run_capture_url(
+        "na", "vercel", "deploy", "--prebuilt", "--target={{ env }}", f"--token={token}", *extra
+    )
+    emit_deployment_url(url)

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@prb/devkit",
+  "description": "Personal configuration files and reusable scripts",
+  "license": "MIT",
+  "type": "module",
+  "version": "1.0.0",
+  "author": {
+    "name": "Paul Razvan Berg",
+    "url": "https://github.com/PaulRBerg"
+  },
+  "bugs": {
+    "url": "https://github.com/PaulRBerg/devkit/issues"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.5.0",
+    "prettier": "^3.8.3",
+    "vitest": "^3.2.4"
+  },
+  "peerDependencies": {
+    "vitest": ">=2.0.0"
+  },
+  "peerDependenciesMeta": {
+    "vitest": {
+      "optional": true
+    }
+  },
+  "exports": {
+    "./biome": "./biome/base.jsonc",
+    "./biome/base": "./biome/base.jsonc",
+    "./biome/ui": "./biome/ui.jsonc",
+    "./prettier": "./.prettierrc.js",
+    "./tsconfig/base": "./tsconfig/base.json",
+    "./tsconfig/build": "./tsconfig/build.json",
+    "./tsconfig/next": "./tsconfig/next.json",
+    "./vitest": "./vitest/base.js"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "files": [
+    "biome/",
+    "just/",
+    "tsconfig/",
+    "vitest/",
+    ".prettierrc.js",
+    ".prettierrc.json"
+  ],
+  "keywords": [
+    "biome",
+    "config",
+    "devkit",
+    "prettier",
+    "tsconfig",
+    "typescript",
+    "vitest"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/PaulRBerg/devkit.git"
+  }
+}

package/tsconfig/base.json

@@ -0,0 +1,18 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "compilerOptions": {
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "lib": ["ESNext"],
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "noEmit": true,
+    "noFallthroughCasesInSwitch": true,
+    "noImplicitReturns": true,
+    "resolveJsonModule": true,
+    "skipLibCheck": true,
+    "sourceMap": true,
+    "strict": true,
+    "target": "ESNext"
+  }
+}

package/tsconfig/build.json

@@ -0,0 +1,16 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "extends": "./base.json",
+  "compilerOptions": {
+    "declaration": true,
+    "inlineSources": true,
+    "declarationMap": true,
+    "emitDecoratorMetadata": true,
+    "experimentalDecorators": true,
+    "forceConsistentCasingInFileNames": true,
+    "noEmit": false,
+    "removeComments": true,
+    "skipLibCheck": true,
+    "stripInternal": true
+  }
+}

package/tsconfig/next.json

@@ -0,0 +1,18 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "extends": "./base.json",
+  "compilerOptions": {
+    "allowJs": true,
+    "isolatedModules": true,
+    "incremental": true,
+    "jsx": "preserve",
+    "lib": ["dom", "dom.iterable", "ESNext"],
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "plugins": [
+      {
+        "name": "next"
+      }
+    ]
+  }
+}

package/vitest/base.js

@@ -0,0 +1,32 @@
+import { defineConfig, mergeConfig } from "vitest/config";
+
+/**
+ * @typedef {Object} DevkitVitestOptions
+ * @property {"node" | "jsdom" | "happy-dom"} [environment]
+ * @property {string[]} [setupFiles]
+ * @property {boolean} [coverage]
+ */
+
+/**
+ * @param {DevkitVitestOptions} [options]
+ */
+export function defineDevkitConfig(options = {}) {
+  const isCI = Boolean(process.env.CI);
+
+  const baseConfig = {
+    test: {
+      coverage: options.coverage ? { provider: "v8" } : undefined,
+      environment: options.environment ?? "node",
+      globals: true,
+      reporters: isCI ? ["basic"] : ["verbose"],
+      retry: isCI ? 2 : 0,
+      setupFiles: options.setupFiles,
+      testTimeout: isCI ? 30_000 : 10_000,
+    },
+  };
+
+  return defineConfig(baseConfig);
+}
+
+// Re-export for merging with existing vite configs
+export { mergeConfig };