ts-stack

TypeScript Stack Harness

The TS side of the harness. Fast, Rust-based tooling so PostToolUse hooks finish in under a second.

Tool choices (and why)

Role	Tool	Why
Format	Biome	Rust, ~50x faster than Prettier, same config for JS/TS/JSON/JSX
Lint	Oxlint	Rust, 50–100x faster than ESLint, covers ~400 common ESLint rules
Type check	tsc --noEmit	Still the only source of truth for types
Architecture	dependency-cruiser or @softarc/sheriff	Layer boundary enforcement
Dead code	Knip	Finds unused exports/files/deps (Vercel deleted 300k LOC with it)

Why NOT ESLint?

ESLint is fine but Node-based — PostToolUse hooks need to finish in <1s to feel responsive. Oxlint covers the common rules. If you need rules Oxlint doesn't have, run ESLint in CI, not in the hook.

Dependency-cruiser vs Sheriff

• dependency-cruiser: rule-based, framework-agnostic, regex path matching. Best for gradual adoption on existing codebases.
• @softarc/sheriff: tag-based, ESLint plugin, enforces a module graph you declare. Best for greenfield monorepos with strict DDD layering.

Pick one. Don't run both.

Config templates

Use ${CLAUDE_PLUGIN_ROOT}/templates/biome.json as the starting point. It has:

• 2-space indent, LF line endings
• Import organization enabled
• noExplicitAny as error in strict mode
• Recommended rules enabled

Architecture enforcement example

Clean architecture boundaries for a typical Node.js backend:

src/
├── domain/         # No imports from anything below
├── application/    # May import domain
├── infrastructure/ # May import domain + application
└── interfaces/     # May import everything below

dependency-cruiser config enforcing this:

// .dependency-cruiser.js (NOTE: protected by pre-config-protect hook)
module.exports = {
  forbidden: [
    {
      name: 'domain-no-outside',
      severity: 'error',
      from: { path: '^src/domain' },
      to: { path: '^src/(application|infrastructure|interfaces)' },
    },
    {
      name: 'application-no-infrastructure',
      severity: 'error',
      from: { path: '^src/application' },
      to: { path: '^src/infrastructure' },
    },
  ],
};

How the hook talks to these tools

When you Write/Edit a .ts/.tsx file, post-edit-lint.js runs:

1. biome format --write <file> (silent auto-fix)
2. oxlint --fix <file> (silent auto-fix)
3. oxlint <file> (collect remaining violations)
4. If violations remain, returns them as additionalContext

tsc is NOT run in the hook (too slow for per-file). It's in lefthook pre-commit and CI.

Key learnings

• Biome's JSON parser is stricter than tsconfig's: if tsconfig.json has trailing commas, Biome will format them out. Usually fine — tsc accepts both.
• Oxlint does not read .eslintrc: configure via .oxlintrc.json or biome.json (Biome's lint side is compatible).
• monorepos: run Biome and Oxlint from the repo root, not per-package. They're fast enough and you avoid config divergence.

Related Skills

• edit-lint-feedback-loop — how PostToolUse hooks work end-to-end
• architecture-enforcement — dependency-cruiser deep dive
• harness-setup — bootstrap workflow

Gotchas

See gotchas.md.