modern-tooling

name: modern-tooling description: Opinionated tooling and conventions for modern JavaScript/TypeScript projects. Use when setting up new projects, configuring ESLint/Prettier, monorepos, library publishing, or establishing coding standards. version: 1.0.0 author: with-philia license: MIT tags: [TypeScript, JavaScript, Tooling, ESLint, Monorepo, Testing] dependencies: [eslint, typescript, vitest, pnpm] allowed-tools: Bash(ni, nr, nu)

Modern Tooling & Standards

This skill provides a comprehensive guide to setting up and maintaining modern JavaScript and TypeScript projects. It covers coding practices, tooling choices, and configuration standards to ensure high code quality and developer productivity.

Coding Practices

Code Organization

• Single Responsibility: Each source file should have a clear, focused scope.
• Modularization: Break large files into smaller, manageable modules.
• Type Separation: Define types and interfaces in dedicated types.ts files or types/ directories.
• Constants: Centralize constants in constants.ts to avoid magic numbers/strings.

Runtime Environment

• Isomorphic Code: Strive for runtime-agnostic code that works across Node.js, browsers, and workers.
• Environment Indicators: Explicitly mark environment-specific code with comments:

  // @env node
  // @env browser
  

TypeScript Best Practices

• Explicit Returns: Declare return types for functions to improve readability and catch errors early.
• Type Definitions: Avoid complex inline types; extract them into named type or interface definitions.
• Strict Mode: Always enable strict: true in tsconfig.json.

Testing (Vitest)

• Co-location: Place test files next to source files (e.g., foo.ts → foo.test.ts).
• BDD Style: Use describe and it for structuring tests.
• Snapshots: Use toMatchSnapshot for complex object verification and toMatchFileSnapshot for large text outputs.

Tooling Stack

Package Management (ni)

We recommend using ni (npm i) to automatically detect and use the correct package manager (pnpm, yarn, npm).

TypeScript Configuration

Recommended tsconfig.json base:

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

Linting & Formatting

We use a unified ESLint configuration that handles both linting and formatting (replacing Prettier).

export default standardConfig();

Workflow: Run nr lint --fix to automatically format code and fix issues.

Git Hooks

Automate checks before commit using simple-git-hooks and lint-staged.

{
  "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"
  }
}

Monorepo Management (pnpm)

Use pnpm-workspace.yaml with named catalogs for consistent dependency versions across packages.

References