dev-specialismsinit-local-tooling

name

dev-specialisms:init-local-tooling

description

Initialize and configure local development tooling for TypeScript, Rust, and Python projects including monorepos. Use when setting up linting (ESLint, Biome, clippy, ruff), formatting (Prettier, rustfmt, ruff), type checking (tsc, mypy), testing (Vitest, Jest, cargo test, pytest), Git hooks (lefthook for commit-msg, pre-commit, pre-push), GitHub Actions workflows, package publishing (npm, crates.io, PyPI), version management (Changesets), and automated releases. Covers both single-language projects and multi-language monorepos using Nx + pnpm workspaces.

Local Tooling Initialization

Comprehensive setup for linting, formatting, type checking, testing, Git hooks, CI/CD, and publishing across TypeScript, Rust, and Python projects.

When to Use This Skill

Use this skill when you need to:

• Initialize tooling for a new TypeScript/Rust/Python project
• Set up monorepo with Nx + pnpm workspaces
• Configure Git hooks with lefthook (conventional commits, pre-commit, pre-push)
• Add GitHub Actions for CI/CD
• Set up automated publishing to npm/crates.io/PyPI
• Configure version bumping and changelog generation with Changesets
• Migrate from Husky to lefthook
• Choose between ESLint+Prettier vs Biome for TypeScript

Quick Start

TypeScript Project

Automated setup:

./scripts/init_typescript.sh

Choose tooling:

• Biome (recommended) - Fast, all-in-one, modern
• ESLint + Prettier - Traditional, highly configurable

What you get:

• Linting and formatting
• TypeScript strict mode
• Vitest for testing
• Package.json scripts

→ See: references/typescript.md

Rust Project

Manual setup (opinionated configs in assets/):

# Tools come with Rust
rustup component add rustfmt clippy

# Optional: Enhanced tooling
brew install cargo-nextest cargo-deny

# Copy configs from assets/configs/rust/
cp assets/configs/rust/rustfmt.toml .
cp assets/configs/rust/clippy.toml .

→ See: references/rust.md

Python Project

Using uv (recommended):

# Install uv
brew install uv

# Create project
uv init my-project
cd my-project

# Add dev dependencies
uv add --dev ruff mypy pytest

# Copy config from assets/
cp assets/configs/python/pyproject.toml .

→ See: references/python.md

Monorepo Setup

Create Nx + pnpm monorepo:

./scripts/init_monorepo.sh

Or manually:

npx create-nx-workspace@latest my-monorepo
# Choose: pnpm + integrated monorepo

→ See: references/monorepo.md

---

Workflow Decision Tree

1. Choose Project Type

Single Language Project → Use language-specific init script or manual setup → See Quick Start above

Monorepo (Multiple Packages) → Set up Nx + pnpm workspaces → See references/monorepo.md

2. Configure Git Hooks

Automated setup:

./scripts/setup_lefthook.sh

This configures:

• commit-msg - Conventional commits validation
• pre-commit - Format and lint staged files
• pre-push - Full validation (lint, type-check, test, build)

→ See: references/git-hooks.md

3. Set Up CI/CD

Copy workflow templates:

# Basic CI
cp assets/workflows/ci.yml .github/workflows/

# Language-specific workflows available in assets/

→ See: references/ci-cd.md

4. Configure Publishing (Optional)

For npm packages:

./scripts/setup_changesets.sh

Then copy publishing workflows from assets/workflows/.

→ See:

• references/version-management.md
• references/publishing.md

---

Language-Specific Guides

TypeScript/JavaScript

Tooling options:

• Biome - Fast, opinionated, all-in-one (recommended for new projects)
• ESLint + Prettier - Traditional, highly configurable (recommended for existing projects)

Testing:

• Vitest - Modern, fast, Vite-based (recommended)
• Jest - Established, widely used

Key decisions:

• Choose Biome for speed and simplicity
• Choose ESLint+Prettier for existing projects or specific plugins

→ Full guide: references/typescript.md

Rust

Built-in tools:

• rustfmt - Code formatting
• clippy - Linting
• cargo test - Testing

Enhanced tools:

• cargo-nextest - Faster test runner
• cargo-deny - Dependency security
• cargo-make - Task runner

→ Full guide: references/rust.md

Python

Modern stack (recommended):

• uv - Fast package manager
• ruff - Fast linting + formatting (replaces black, isort, flake8)
• mypy - Type checking
• pytest - Testing

→ Full guide: references/python.md

---

Git Hooks with lefthook

Why lefthook?

• Language-agnostic - Works across TS, Rust, Python
• Fast - Parallel execution, written in Go
• Simple - Single YAML config
• Better than Husky - Faster, works across languages

Setup

Automated:

./scripts/setup_lefthook.sh

Manual:

brew install lefthook
lefthook install

Configuration Example

lefthook.yml:

commit-msg:
  commands:
    commitlint:
      run: npx commitlint --edit {1}

pre-commit:
  parallel: true
  commands:
    format:
      glob: "*.{ts,rs,py}"
      run: format-staged-files {staged_files}
      stage_fixed: true

pre-push:
  commands:
    validate:
      run: ./scripts/validate_all.sh

→ Full guide: references/git-hooks.md

---

Monorepo Management

Nx + pnpm Workspaces

Key principle: Nx builds on top of pnpm, doesn't replace it.

• pnpm workspaces - Dependency management
• Nx - Task orchestration, caching, affected commands

Benefits

• Run tasks only for affected packages
• Intelligent caching
• Parallel execution
• Supports multiple languages

Common Commands

# Run target for all packages
nx run-many --target=build --all

# Run only for affected
nx affected --target=test

# Visualize dependencies
nx graph

→ Full guide: references/monorepo.md

---

Version Management & Publishing

Changesets Workflow

Recommended for monorepos and npm packages.

1. Add changeset:

pnpm changeset
# Select packages, type (major/minor/patch), write summary

2. Version packages:

pnpm changeset version
# Updates package.json, generates CHANGELOG.md

3. Publish:

pnpm changeset publish
git push --follow-tags

Automated Publishing

Use GitHub Actions to automate releases:

Copy workflow:

cp assets/workflows/publish-changesets.yml .github/workflows/

This creates "Version Packages" PR on main when changesets exist.

→ See:

• references/version-management.md
• references/publishing.md

---

CI/CD Setup

Match Local Validation

Best practice: Run same checks in CI as local pre-push hook.

GitHub Actions templates:

• ci.yml - Basic linting, testing, building
• publish-npm.yml - Automated npm publishing
• publish-crates.yml - Automated crates.io publishing
• publish-pypi.yml - Automated PyPI publishing

Matrix Testing

Test across multiple versions:

strategy:
  matrix:
    node-version: [18, 20, 21]
    os: [ubuntu-latest, macos-latest]

Nx Monorepo CI

Use affected commands to only test changed packages:

nx affected --target=test
nx affected --target=build

→ Full guide: references/ci-cd.md

---

Common Tasks

Initialize TypeScript Project

Automated:

./scripts/init_typescript.sh --biome
# or
./scripts/init_typescript.sh --eslint-prettier

Creates:

• tsconfig.json (strict mode)
• Linting config (biome.json or eslint.config.js)
• Formatting config (.prettierrc.json if ESLint)
• Testing config (vitest.config.ts)
• Package.json scripts

Set Up Git Hooks

./scripts/setup_lefthook.sh

Configures:

• Conventional commits validation
• Pre-commit: lint/format staged files
• Pre-push: full validation

Configure Changesets

./scripts/setup_changesets.sh

Sets up:

• .changeset/ directory
• Package.json scripts
• Public access configuration

Full Validation

./scripts/validate_all.sh

Runs:

• Format checking
• Linting
• Type checking
• Tests
• Builds

---

Bundled Resources

Scripts (scripts/)

Setup scripts:

• init_typescript.sh - Initialize TypeScript project
• setup_lefthook.sh - Configure Git hooks
• setup_changesets.sh - Set up version management
• validate_all.sh - Run all checks (used by pre-push)

Usage:

./scripts/script_name.sh

All scripts check if tools are installed/up-to-date before proceeding.

Config Templates (assets/configs/)

TypeScript:

• tsconfig.strict.json - Strict TypeScript config
• biome.json - Biome configuration
• eslint.config.js - ESLint flat config
• .prettierrc.json - Prettier configuration

Rust:

• rustfmt.toml - Rustfmt configuration
• clippy.toml - Clippy lints
• deny.toml - Cargo-deny configuration

Python:

• pyproject.toml - ruff, mypy, pytest config
• ruff.toml - Standalone ruff config

Monorepo:

• nx.json - Nx configuration
• pnpm-workspace.yaml - pnpm workspaces

Git Hooks:

• lefthook.yml - Complete lefthook config
• commitlint.config.js - Conventional commits

GitHub Workflows:

• ci.yml - Basic CI
• publish-changesets.yml - Automated releases
• publish-npm.yml - npm publishing
• publish-crates.yml - crates.io publishing
• publish-pypi.yml - PyPI publishing

Reference Documentation (references/)

Language guides:

• typescript.md - ESLint+Prettier vs Biome, testing, monorepo
• rust.md - rustfmt, clippy, cargo-nextest, cargo-deny
• python.md - ruff, mypy, pytest, uv vs poetry

Infrastructure:

• monorepo.md - Nx + pnpm workspaces setup
• git-hooks.md - lefthook configuration
• ci-cd.md - GitHub Actions workflows
• publishing.md - npm, crates.io, PyPI publishing
• version-management.md - Changesets workflow

---

Best Practices

1. Use lefthook over Husky - Faster, language-agnostic
2. Match CI and local - Same checks in pre-push and CI
3. Choose Biome for new TS projects - Faster, simpler
4. Use Nx affected commands - Only test changed packages
5. Automate versioning - Use Changesets for npm packages
6. Conventional commits - Enables automated changelogs
7. Pre-commit: staged files - Fast feedback
8. Pre-push: full validation - Catch issues before pushing
9. Type-check everything - TypeScript, mypy, clippy
10. Test before publish - Always run tests in pre-publish

---

Troubleshooting

Hooks Not Running

Check installation:

lefthook install
ls -la .git/hooks/

Test manually:

lefthook run pre-commit

Format Conflicts

ESLint + Prettier conflicts:

• Ensure eslint-config-prettier is last in config
• Run Prettier separately from ESLint

Biome + Prettier conflicts:

• Don't use both - choose one
• Biome is drop-in Prettier replacement

CI Failures

Debugging:

1. Run ./scripts/validate_all.sh locally
2. Check CI runs same commands
3. Verify Node/Rust/Python versions match
4. Check caching is working

---

Quick Reference

Setup new TypeScript project:

./scripts/init_typescript.sh

Setup Git hooks:

./scripts/setup_lefthook.sh

Setup Changesets:

./scripts/setup_changesets.sh

Run full validation:

./scripts/validate_all.sh

Common commands:

# TypeScript
npm run lint && npm run type-check && npm test

# Rust
cargo fmt -- --check && cargo clippy -- -D warnings && cargo test

# Python
ruff check . && mypy . && pytest

# Monorepo
nx affected --target=test
nx run-many --target=build --all

# Changesets
pnpm changeset
pnpm changeset version
pnpm changeset publish

---

Getting Help

• TypeScript: See references/typescript.md
• Rust: See references/rust.md
• Python: See references/python.md
• Monorepo: See references/monorepo.md
• Git Hooks: See references/git-hooks.md
• CI/CD: See references/ci-cd.md
• Publishing: See references/publishing.md and references/version-management.md