Hairyf's Preferences

Hairyf's Preferences

This skill covers Hairyf's preferred tooling, configurations, and best practices for web development. This skill is opinionated.

Quick Summary

---

Global Preferences

High-level cross-cutting preferences that should be respected whenever possible:

"specify" keyword

When a task is marked with "specify" (for example: "specify this repo according to hairy"):

• Treat it as a request to inspect the current project and optimize it until it matches these preferences as much as reasonably possible.
• Concretely, this should trigger:
  • Architecture detection and upgrade planning via @skills/​arch-upkeep and the relevant arch-* skills.
  • Preference-aware stack choices (prefer unjs ecosystem via @skills/​unjs).
  • Dependency freshness checks and upgrades via @skills/​taze.
  • A final pass of lint + typecheck (and tests if present) before considering the "specify" task done.

Prefer unjs ecosystem frameworks

• When choosing frameworks or runtimes (SSR, API, tooling, dev server, etc.), prefer unjs ecosystem projects first (for example Nuxt, Nitro, h3, unstorage, unplugin, unocss, ofetch, and other unjs-maintained tools).
• Only fall back to non-unjs options when there is a clear, justified reason (missing feature, ecosystem constraint, or legacy requirements).
• For concrete choices, recipes, and defaults, delegate to @skills/​unjs and follow its recommendations.

Architecture must map to arch-* skills

• A project’s architecture should always map to one of the canonical arch-* stacks (tsdown library, CLI, monorepo, unplugin, webext, vscode, etc.).
• When the current shape does not match any target cleanly, treat it as an upgrade opportunity and plan a migration instead of adding more ad‑hoc structure.
• Use @skills/​arch-upkeep to:
  • Detect the current architecture.
  • Choose the best target arch-* skill(s).
  • Orchestrate an incremental migration to that architecture.

Keep dependencies fresh with taze

• Dependencies should be kept continuously fresh, not only during big refactors.
• Prefer using taze (see @skills/​taze) to:
  • Audit outdated dependencies.
  • Perform controlled upgrades (minor/​patch regularly; majors with explicit review).
  • Align versions across a monorepo using pnpm workspaces and catalogs.
• Avoid hand-editing versions in package.json unless there is a specific reason not to follow taze’s suggestions.

Always finish with lint + typecheck

• After implementing any non-trivial change (feature, refactor, config change, dependency upgrade, CI change, etc.), always run lint and typecheck before considering the task done.
• Standard scripts:
  • nr lint → ESLint via @antfu/​eslint-config.
  • nr typecheck → TypeScript in strict mode (project-wide).
• For CI and Git hooks:
  • Ensure pre-commit hooks at least run lint on staged files.
  • Ensure GitHub Actions (or other CI) run both lint and typecheck on PRs and main pushes.

---

Core Stack

Package Manager (pnpm)

Use pnpm as the package manager.

For monorepo setups, use pnpm workspaces:

# pnpm-workspace.yaml
packages:
  - 'packages/​*'

Use pnpm named catalogs in pnpm-workspace.yaml to manage dependency versions:

Catalog names are not limited to the above and can be adjusted based on needs. Avoid using default catalog.

@antfu/​ni

Use @antfu/​ni for unified package manager commands. It auto-detects the package manager (pnpm/​npm/​yarn/​bun) based on lockfile.

Install globally with pnpm i -g @antfu/​ni if the commands are not found.

TypeScript (Strict Mode)

Always use TypeScript with strict mode enabled.

{
  "compilerOptions": {
    "target": "ESNext",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "resolveJsonModule": true,
    "isolatedModules": true,
    "noEmit": true
  }
}

ESM (ECMAScript Modules)

Always work in ESM mode. Set "type": "module" in package.json.

---

Code Quality

ESLint (@antfu/​eslint-config)

Use @antfu/​eslint-config for both formatting and linting. This eliminates the need for Prettier.

Create eslint.config.js with // @ts-check comment:

// @ts-check
import antfu from '@antfu/​eslint-config'

export default antfu()

Add script to package.json:

{
  "scripts": {
    "lint": "eslint ."
  }
}

When getting linting errors, try to fix them with nr lint --fix. Don't add lint:fix script.

Git Hooks (simple-git-hooks + lint-staged)

Use simple-git-hooks with lint-staged for pre-commit linting:

{
  "simple-git-hooks": {
    "pre-commit": "pnpm i --frozen-lockfile --ignore-scripts --offline && npx lint-staged"
  },
  "lint-staged": {
    "*": "eslint --fix"
  },
  "scripts": {
    "prepare": "npx simple-git-hooks"
  }
}

Unit Testing (Vitest)

Use Vitest for unit testing.

{
  "scripts": {
    "test": "vitest"
  }
}

Conventions:

• Place test files next to source files: foo.ts → foo.test.ts (same directory)
• High-level tests go in tests/ directory in each package
• Use describe and it API (not test)
• Use expect API for assertions
• Use assert only for TypeScript null assertions
• Use toMatchSnapshot for complex output assertions
• Use toMatchFileSnapshot with explicit file path and extension for language-specific output (exclude those files from linting)

---

Project Setup

Publishing (Library Projects)

For library projects, publish through GitHub Releases triggered by bumpp:

{
  "scripts": {
    "release": "bumpp -r"
  }
}

Documentation (VitePress)

Use VitePress for documentation. Place docs under docs/ directory.

docs/
├── .vitepress/
│   └── config.ts
├── index.md
└── guide/
    └── getting-started.md

Add script to package.json:

{
  "scripts": {
    "docs:dev": "vitepress dev docs",
    "docs:build": "vitepress build docs"
  }
}

---

References

Global Preferences

Project Setup

Development