TypeScript Project Setup

Comprehensive configuration templates and guidance for setting up TypeScript projects with modern tooling, testing frameworks, and code quality enforcement.

Purpose

This skill provides standardized configurations and best practices for TypeScript projects, including:

TypeScript configuration with ES modules or CommonJS
Choice of Biome (recommended) or ESLint+Prettier for linting/formatting
Vitest for unit and integration testing (optional)
Playwright for end-to-end testing (optional)
Husky for pre-commit hooks
Makefile for common operations
GitHub Actions for CI/CD
Package.json scripts for common workflows

When to Use

Use this skill when:

Starting a new TypeScript project
Adding TypeScript to an existing JavaScript project
Setting up testing infrastructure (unit + e2e)
Implementing code quality gates and pre-commit hooks
Standardizing configurations across multiple TypeScript projects
Need guidance on recommended dependencies and versions

Initial Setup Questions

When using this skill, Claude will ask:

Module System:

ES Modules (recommended for new projects) - Modern, bundler-friendly
CommonJS - Traditional Node.js, better for legacy compatibility

Linting/Formatting Tool:

Biome (recommended) - Modern, fast, all-in-one tool
ESLint + Prettier - Traditional, wider ecosystem support
None - Rely on TypeScript strict mode only (minimal approach)

Testing Strategy:

Vitest only - Unit and integration testing
Playwright only - E2E and component testing
Vitest + Playwright - Comprehensive testing (unit + E2E)
None - No testing setup

Pre-commit Hooks:

Yes - Set up Husky with quality checks
No - Manual quality checks only

Project Type:

Vite Frontend - Browser app with bundler mode
Node.js Backend - Server-side application
CLI Tool - Command-line tool
Library - Reusable package with type definitions
General - Standard TypeScript project

Project Structure

Recommended directory structure:

project-root/
├── src/ # TypeScript source files
│ ├── **/*.ts
│ └── **/*.tsx
├── tests/ # Test files
│ ├── **/*.test.ts # Vitest unit tests (if using Vitest)
│ └── **/*.spec.ts # Test files (Vitest or Playwright)
├── dist/ # Compiled output (if not using bundler)
├── .husky/ # Git hooks (if enabled)
│ └── pre-commit
├── .github/ # GitHub Actions workflows
│ └── workflows/
│ └── checks.yml
├── tsconfig.json # TypeScript config
├── biome.json # Biome config (if using Biome)
├── eslint.config.js # ESLint config (if using ESLint)
├── .prettierrc.json # Prettier config (if using Prettier)
├── vitest.config.js # Vitest config (if using Vitest)
├── playwright.config.ts # Playwright config (if using Playwright)
├── Makefile # Common operations
└── package.json

Configuration Templates

1. TypeScript Configuration (tsconfig.json)

For Vite/Bundler Projects (Frontend)

{
 "compilerOptions": {
 "target": "ES2022",
 "lib": ["ES2022", "DOM", "DOM.Iterable"],
 "module": "ESNext",
 "skipLibCheck": true,

 /* Bundler mode */
 "moduleResolution": "bundler",
 "allowImportingTsExtensions": true,
 "resolveJsonModule": true,
 "isolatedModules": true,
 "noEmit": true,

 /* Linting */
 "strict": true,
 "noUnusedLocals": true,
 "noUnusedParameters": true,
 "noFallthroughCasesInSwitch": true,
 "forceConsistentCasingInFileNames": true
 },
 "include": ["src"]
}

Key settings for Vite:

```
"moduleResolution": "bundler"
```
- Modern bundler-aware resolution
```
"noEmit": true
```
- Vite handles compilation, not tsc
```
"allowImportingTsExtensions": true
```
- Import
```
.ts
```
files directly
```
"isolatedModules": true
```
- Required for bundlers

For Node.js/Backend Projects (ES Modules)

{
 "compilerOptions": {
 "target": "ES2022",
 "module": "ES2022",
 "moduleResolution": "node",
 "esModuleInterop": true,
 "strict": true,
 "noImplicitAny": true,
 "strictNullChecks": true,
 "noUnusedLocals": true,
 "noUnusedParameters": true,
 "lib": ["ES2022"],
 "skipLibCheck": true,
 "forceConsistentCasingInFileNames": true,
 "outDir": "dist",
 "rootDir": "src",
 "declaration": true,
 "resolveJsonModule": true
 },
 "include": ["src/**/*.ts"],
 "exclude": ["node_modules", "dist"]
}

For Node.js/Backend Projects (CommonJS)

{
 "compilerOptions": {
 "target": "ES2020",
 "module": "CommonJS",
 "outDir": "./dist",
 "rootDir": "./src",
 "strict": true,
 "esModuleInterop": true,
 "skipLibCheck": true,
 "forceConsistentCasingInFileNames": true,
 "resolveJsonModule": true
 },
 "include": ["src/**/*"],
 "exclude": ["node_modules"]
}

When to use CommonJS:

Legacy Node.js projects
Enterprise environments with older Node versions
Projects that depend on CommonJS-only packages
When ES modules cause compatibility issues

2. Linting and Formatting

Option A: Biome (Recommended)

Configuration (biome.json):

{
 "$schema": "https://biomejs.dev/schemas/1.9.4/schema.json",
 "organizeImports": {
 "enabled": true
 },
 "formatter": {
 "enabled": true,
 "indentStyle": "space",
 "indentWidth": 2,
 "lineWidth": 120,
 "lineEnding": "lf"
 },
 "linter": {
 "enabled": true,
 "rules": {
 "recommended": true,
 "suspicious": {
 "noExplicitAny": "warn"
 },
 "style": {
 "useConst": "error",
 "noNonNullAssertion": "warn"
 }
 }
 },
 "javascript": {
 "formatter": {
 "quoteStyle": "single",
 "semicolons": "asNeeded",
 "trailingCommas": "es5"
 }
 },
 "files": {
 "ignore": [
 "dist",
 "node_modules",
 "test-results",
 "playwright-report",
 "*.config.js",
 "*.config.ts"
 ]
 }
}

Package.json scripts:

{
 "scripts": {
 "lint": "biome check .",
 "lint:fix": "biome check --write .",
 "format": "biome format --write .",
 "check": "biome check . && tsc --noEmit"
 }
}

Dependencies:

npm install --save-dev @biomejs/biome

Biome advantages:

10-100x faster than ESLint (Rust-based)
Single tool for linting + formatting + import sorting
Zero config needed (sensible defaults)
Simple configuration file
Modern, actively developed

Code style:

Single quotes
Semicolons only when needed (ASI-friendly)
Trailing commas in ES5 contexts (arrays, objects)
120 character line width
2-space indentation

Option B: ESLint + Prettier (Traditional)

ESLint Configuration (eslint.config.js):

import eslint from '@eslint/js'
import tseslint from '@typescript-eslint/eslint-plugin'
import tsParser from '@typescript-eslint/parser'

export default [
 eslint.configs.recommended,
 {
 files: ['**/*.ts', '**/*.js'],
 languageOptions: {
 parser: tsParser,
 ecmaVersion: 2020,
 sourceType: 'module',
 globals: {
 // Browser globals
 window: 'readonly',
 document: 'readonly',
 console: 'readonly',
 // Node globals
 process: 'readonly',
 module: 'readonly',
 require: 'readonly',
 __dirname: 'readonly'
 }
 },
 plugins: {
 '@typescript-eslint': tseslint
 },
 rules: {
 ...tseslint.configs.recommended.rules,
 '@typescript-eslint/no-unused-vars': ['error', {
 argsIgnorePattern: '^_',
 varsIgnorePattern: '^_'
 }],
 '@typescript-eslint/no-explicit-any': 'warn',
 'no-console': 'warn',
 'semi': ['error', 'never'],
 'quotes': ['error', 'single', { avoidEscape: true }],
 'comma-dangle': ['error', 'never']
 }
 },
 {
 files: ['**/*.test.js', '**/*.test.ts'],
 rules: {
 'no-console': 'off'
 }
 }
]

Prettier Configuration (.prettierrc.json):

{
 "semi": false,
 "singleQuote": true,
 "trailingComma": "none",
 "printWidth": 100,
 "tabWidth": 2,
 "arrowParens": "avoid"
}

Package.json scripts:

{
 "scripts": {
 "lint": "eslint src/**/*.{js,ts}",
 "lint:fix": "eslint src/**/*.{js,ts} --fix",
 "lint:errors-only": "eslint src/**/*.{js,ts} --quiet",
 "format": "prettier --write src/**/*.{js,ts}",
 "format:check": "prettier --check src/**/*.{js,ts}",
 "check": "npm run typecheck && npm run lint && npm run format:check"
 }
}

Dependencies:

npm install --save-dev \
 eslint @eslint/js \
 @typescript-eslint/eslint-plugin \
 @typescript-eslint/parser \
 prettier

Code style:

Single quotes
No semicolons
No trailing commas
100 character line width
2-space indentation

Option C: No Linting (Minimal)

When to use:

Small, simple projects
Relying on TypeScript strict mode for type safety
Team has strong IDE setup and conventions
CI handles quality checks

Package.json scripts:

{
 "scripts": {
 "check": "tsc --noEmit"
 }
}

Note: TypeScript's strict mode catches many issues that linters would, but you lose style consistency enforcement.

3. Testing Configurations

Option A: Vitest Only

When to use: Unit testing, integration testing, API testing (no browser needed).

Configuration (vitest.config.js):

import {defineConfig} from 'vitest/config'

export default defineConfig({
 test: {
 environment: 'jsdom',
 globals: true,
 setupFiles: ['./tests/setup.js'],
 include: ['./tests/**/*.test.js', './tests/**/*.test.ts', './tests/**/*.spec.ts'],
 coverage: {
 provider: 'v8',
 reporter: ['text', 'json', 'html']
 }
 }
})

Note: Vitest works without a config file - it will auto-discover tests. Config is optional for customization.

Package.json scripts:

{
 "scripts": {
 "test": "vitest run",
 "test:watch": "vitest",
 "test:coverage": "vitest run --coverage",
 "test:ui": "vitest --ui"
 }
}

Dependencies:

npm install --save-dev vitest @vitest/coverage-v8

Option B: Playwright Only

When to use: E2E testing, browser testing, visual testing.

Configuration (playwright.config.ts):

import { defineConfig, devices } from '@playwright/test'

export default defineConfig({
 testDir: './tests',
 fullyParallel: true,
 forbidOnly: !!process.env.CI,
 retries: process.env.CI ? 2 : 0,
 workers: process.env.CI ? 1 : undefined,
 reporter: 'html',

 use: {
 baseURL: process.env.BASE_URL || 'http://localhost:3000',
 trace: 'on-first-retry',
 screenshot: 'only-on-failure',
 },

 projects: [
 {
 name: 'chromium',
 use: { ...devices['Desktop Chrome'] },
 },
 ],

 webServer: process.env.BASE_URL ? undefined : {
 command: 'npm run preview',
 url: 'http://localhost:3000',
 reuseExistingServer: !process.env.CI,
 },
})

Package.json scripts:

{
 "scripts": {
 "test": "playwright test",
 "test:headed": "playwright test --headed",
 "test:ui": "playwright test --ui"
 }
}

Dependencies:

npm install --save-dev @playwright/test

Option C: Vitest + Playwright

When to use: Comprehensive testing strategy (fast unit tests + thorough E2E tests).

Testing strategy:

```
.test.ts
```
files → Vitest (unit tests)
```
.spec.ts
```
files → Playwright (E2E tests)

Package.json scripts:

{
 "scripts": {
 "test": "vitest run",
 "test:watch": "vitest",
 "test:coverage": "vitest run --coverage",
 "test:ui": "vitest --ui",
 "test:e2e": "playwright test",
 "test:e2e:ui": "playwright test --ui",
 "test:e2e:report": "playwright show-report"
 }
}

4. Pre-commit Hooks with Husky

Setup Husky:

npm install --save-dev husky
npx husky init

Pre-commit hook (.husky/pre-commit):

#!/usr/bin/env sh
. "$(dirname -- "$0")/_/husky.sh"

npm run quality:commit

Package.json scripts:

For Biome:

{
 "scripts": {
 "quality": "npm run check && npm run test",
 "quality:commit": "biome check . && tsc --noEmit && npm run test",
 "prepare": "husky"
 }
}

For ESLint+Prettier:

{
 "scripts": {
 "quality": "npm run typecheck && npm run lint && npm run format:check && npm run test",
 "quality:commit": "npm run typecheck && npm run lint:errors-only && npm run test",
 "prepare": "husky"
 }
}

For minimal (no linting):

{
 "scripts": {
 "quality": "npm run typecheck && npm run test",
 "quality:commit": "tsc --noEmit && npm run test",
 "prepare": "husky"
 }
}

What runs in pre-commit:

Type checking (fast)
Linting errors only (warnings ignored)
Tests (unit tests only, not E2E)

What NOT to run in pre-commit:

Formatting (too slow, should be editor responsibility)
Full linting with warnings (too noisy)
E2E tests (too slow)

5. Makefile

Common Makefile targets:

.PHONY: help install build test clean lint format check

help:
 @echo "Available targets:"
 @echo " install - Install dependencies"
 @echo " build - Build the project"
 @echo " test - Run tests"
 @echo " clean - Clean build artifacts"
 @echo " lint - Run linting"
 @echo " format - Format code"
 @echo " check - Run all quality checks"

install:
 npm ci

build:
 npm run build

test:
 npm run test

clean:
 rm -rf dist node_modules

lint:
 npm run lint

format:
 npm run format

check:
 npm run quality

6. GitHub Actions

Basic CI workflow (.github/workflows/checks.yml):

name: Checks

on:
 push:
 branches-ignore:
 - main
 pull_request:
 branches:
 - main

permissions: read-all

jobs:
 quality:
 runs-on: ubuntu-latest
 steps:
 - uses: actions/checkout@v4

 - name: Setup Node.js
 uses: actions/setup-node@v4
 with:
 node-version: '20'
 cache: 'npm'

 - name: Install dependencies
 run: npm ci

 - name: Type check
 run: npm run typecheck

 - name: Lint
 run: npm run lint
 if: hashFiles('biome.json', 'eslint.config.js') != ''

 - name: Test
 run: npm run test
 if: hashFiles('vitest.config.js', 'playwright.config.ts') != ''

7. Complete Package.json Examples

For ES Modules + Biome + Vitest:

{
 "name": "my-typescript-project",
 "version": "1.0.0",
 "type": "module",
 "scripts": {
 "dev": "your-dev-command",
 "build": "tsc",
 "typecheck": "tsc --noEmit",
 "test": "vitest run",
 "test:watch": "vitest",
 "test:coverage": "vitest run --coverage",
 "lint": "biome check .",
 "lint:fix": "biome check --write .",
 "format": "biome format --write .",
 "check": "biome check . && tsc --noEmit",
 "quality": "npm run check && npm run test",
 "quality:commit": "biome check . && tsc --noEmit && npm run test",
 "prepare": "husky"
 },
 "devDependencies": {
 "@biomejs/biome": "^1.9.0",
 "@types/node": "^22.0.0",
 "@vitest/coverage-v8": "^2.1.0",
 "husky": "^9.0.0",
 "typescript": "^5.6.0",
 "vitest": "^2.1.0"
 }
}

For CommonJS + No Linting + Vitest:

{
 "name": "my-typescript-project",
 "version": "1.0.0",
 "scripts": {
 "build": "tsc",
 "test": "vitest",
 "coverage": "vitest run --coverage",
 "typecheck": "tsc --noEmit",
 "quality": "npm run typecheck && npm run test",
 "quality:commit": "tsc --noEmit && npm run test",
 "prepare": "husky"
 },
 "devDependencies": {
 "@types/node": "^22.0.0",
 "@vitest/coverage-v8": "^2.1.0",
 "husky": "^9.0.0",
 "typescript": "^5.6.0",
 "vitest": "^2.1.0"
 }
}

Quick Setup Guide

1. Initialize Project

npm init -y
npm install --save-dev typescript

2. Choose Module System

For ES Modules (recommended):

npm pkg set type=module

For CommonJS:

No action needed (default)

3. Initialize TypeScript

npx tsc --init

Then replace with the appropriate config from this skill.

4. Choose Linting/Formatting

Option A: Biome (recommended)

npm install --save-dev @biomejs/biome
npx @biomejs/biome init

Option B: ESLint + Prettier

npm install --save-dev \
 eslint @eslint/js \
 @typescript-eslint/eslint-plugin \
 @typescript-eslint/parser \
 prettier

Option C: None

Skip this step

5. Choose Testing

Option A: Vitest

npm install --save-dev vitest @vitest/coverage-v8

Option B: Playwright

npm init playwright@latest

Option C: Both

npm install --save-dev vitest @vitest/coverage-v8 @playwright/test
npm init playwright@latest

6. Set up Pre-commit Hooks

npm install --save-dev husky
npx husky init
echo "npm run quality:commit" > .husky/pre-commit
chmod +x .husky/pre-commit

7. Create Makefile

Create a

Makefile

with the targets shown above.

8. Set up GitHub Actions

Create

.github/workflows/checks.yml

with the workflow shown above.

Best Practices

1. Module System Choice

ES Modules (recommended for new projects):

Modern, future-proof
Better tree-shaking in bundlers
Native browser support
Required for Vite and modern tools

CommonJS (for legacy compatibility):

Better compatibility with older Node.js
Some npm packages only support CommonJS
Traditional Node.js pattern

2. Type Safety

Enable all strict flags in tsconfig.json
Use
```
noUnusedLocals
```
and
```
noUnusedParameters
```
Avoid
```
any
```
types (linters warn about them)
Prefix unused variables with
```
_
```
if needed

3. Code Style

Biome default: Single quotes, semicolons as needed, trailing commas in ES5 contexts
ESLint+Prettier default: Single quotes, no semicolons, no trailing commas
Consistent 2-space indentation
120 char line width (modern)

4. Testing Strategy

Vitest only: Fast, good for libraries and backend
Playwright only: Essential for frontend apps
Both: Comprehensive coverage for full-stack apps
Keep E2E tests out of pre-commit hooks (too slow)

5. Pre-commit Hooks

Run fast checks only (typecheck, lint errors, unit tests)
Skip slow checks (formatting, warnings, E2E tests)
Let CI handle comprehensive quality checks
Developers should format code via editor

6. CI/CD

Run comprehensive checks in CI (what you skip in pre-commit)
Use caching for faster builds
Separate workflows for PRs vs main branch
Consider coverage thresholds

7. Makefile Usage

Provides consistent interface across projects
Easier for new contributors (single command reference)
Works regardless of language/tooling
Good for complex multi-step operations

Decision Matrix

Criteria	Biome	ESLint+Prettier	None
Speed	Much faster	Slower	Fastest
Simplicity	Single tool	Two tools	No tools
Ecosystem	Growing	Mature, extensive	N/A
Style enforcement	Excellent	Excellent	Manual
Type safety	Via rules	Via rules	TypeScript only

Criteria	ES Modules	CommonJS
Modern	Yes	No
Bundler support	Excellent	Good
Node.js compat	Node 12+	All versions
Future-proof	Yes	Legacy

Criteria	Vitest	Playwright	Both
Unit testing	Excellent	N/A	Excellent
E2E testing	N/A	Excellent	Excellent
Speed	Fast	Slower	Mixed
Setup	Simple	Moderate	Complex

Common Issues and Solutions

Issue: "Cannot find module" errors with ES modules

Solution: Ensure

"type": "module"

is in package.json and use

.js

extension for config files.

Issue: Biome not recognizing TypeScript

Solution: Biome works out of the box with TypeScript. Ensure

biome.json

exists and

@biomejs/biome

is installed.

Issue: ESLint not recognizing TypeScript

Solution: Verify

@typescript-eslint/parser

is specified in

languageOptions.parser

Issue: Pre-commit hook is too slow

Solution: Use

quality:commit

(fast) instead of

quality

(comprehensive). Remove E2E tests from pre-commit.

Issue: Vitest not finding tests

Solution: Vitest auto-discovers tests. Ensure test files match patterns:

**/*.{test,spec}.{js,ts}

Issue: Husky hooks not running

Solution: Ensure

.husky/pre-commit

is executable:

chmod +x .husky/pre-commit

Issue: Make commands not working

Solution: Ensure Makefile uses tabs (not spaces) for indentation.

Project Type Recommendations

Vite Frontend Projects

ES Modules
Biome (faster, modern)
TypeScript with bundler mode
Playwright for E2E testing
Pre-commit hooks
GitHub Actions CI

Node.js Backend Projects

ES Modules (or CommonJS for legacy)
Biome or ESLint+Prettier
TypeScript with node resolution
Vitest for unit tests
Pre-commit hooks
GitHub Actions CI

CLI Tools

CommonJS (better compatibility)
Minimal linting (or none)
TypeScript with CommonJS module
Vitest for unit tests
Pre-commit hooks
GitHub Actions CI

Library Projects

ES Modules with CommonJS output (dual package)
ESLint+Prettier (wider compatibility)
TypeScript with
```
declaration: true
```
Vitest for comprehensive unit testing
Pre-commit hooks with strict checks
GitHub Actions CI with publishing

Monorepo Projects

ES Modules
Biome (single config, fast)
TypeScript project references
Both Vitest + Playwright
Workspace-level pre-commit hooks
GitHub Actions CI with matrix builds

TypeScript Project Setup

Comprehensive configuration templates and guidance for setting up TypeScript projects with modern tooling, testing frameworks, and code quality enforcement.

Purpose

This skill provides standardized configurations and best practices for TypeScript projects, including:

TypeScript configuration with ES modules or CommonJS
Choice of Biome (recommended) or ESLint+Prettier for linting/formatting
Vitest for unit and integration testing (optional)
Playwright for end-to-end testing (optional)
Husky for pre-commit hooks
Makefile for common operations
GitHub Actions for CI/CD
Package.json scripts for common workflows

When to Use

Use this skill when:

Starting a new TypeScript project
Adding TypeScript to an existing JavaScript project
Setting up testing infrastructure (unit + e2e)
Implementing code quality gates and pre-commit hooks
Standardizing configurations across multiple TypeScript projects
Need guidance on recommended dependencies and versions

Initial Setup Questions

When using this skill, Claude will ask:

Module System:

ES Modules (recommended for new projects) - Modern, bundler-friendly
CommonJS - Traditional Node.js, better for legacy compatibility

Linting/Formatting Tool:

Biome (recommended) - Modern, fast, all-in-one tool
ESLint + Prettier - Traditional, wider ecosystem support
None - Rely on TypeScript strict mode only (minimal approach)

Testing Strategy:

Vitest only - Unit and integration testing
Playwright only - E2E and component testing
Vitest + Playwright - Comprehensive testing (unit + E2E)
None - No testing setup

Pre-commit Hooks:

Yes - Set up Husky with quality checks
No - Manual quality checks only

Project Type:

Vite Frontend - Browser app with bundler mode
Node.js Backend - Server-side application
CLI Tool - Command-line tool
Library - Reusable package with type definitions
General - Standard TypeScript project

Project Structure

Recommended directory structure:

project-root/
├── src/ # TypeScript source files
│ ├── **/*.ts
│ └── **/*.tsx
├── tests/ # Test files
│ ├── **/*.test.ts # Vitest unit tests (if using Vitest)
│ └── **/*.spec.ts # Test files (Vitest or Playwright)
├── dist/ # Compiled output (if not using bundler)
├── .husky/ # Git hooks (if enabled)
│ └── pre-commit
├── .github/ # GitHub Actions workflows
│ └── workflows/
│ └── checks.yml
├── tsconfig.json # TypeScript config
├── biome.json # Biome config (if using Biome)
├── eslint.config.js # ESLint config (if using ESLint)
├── .prettierrc.json # Prettier config (if using Prettier)
├── vitest.config.js # Vitest config (if using Vitest)
├── playwright.config.ts # Playwright config (if using Playwright)
├── Makefile # Common operations
└── package.json

Configuration Templates

1. TypeScript Configuration (tsconfig.json)

For Vite/Bundler Projects (Frontend)

{
 "compilerOptions": {
 "target": "ES2022",
 "lib": ["ES2022", "DOM", "DOM.Iterable"],
 "module": "ESNext",
 "skipLibCheck": true,

 /* Bundler mode */
 "moduleResolution": "bundler",
 "allowImportingTsExtensions": true,
 "resolveJsonModule": true,
 "isolatedModules": true,
 "noEmit": true,

 /* Linting */
 "strict": true,
 "noUnusedLocals": true,
 "noUnusedParameters": true,
 "noFallthroughCasesInSwitch": true,
 "forceConsistentCasingInFileNames": true
 },
 "include": ["src"]
}

Key settings for Vite:

```
"moduleResolution": "bundler"
```
- Modern bundler-aware resolution
```
"noEmit": true
```
- Vite handles compilation, not tsc
```
"allowImportingTsExtensions": true
```
- Import
```
.ts
```
files directly
```
"isolatedModules": true
```
- Required for bundlers

For Node.js/Backend Projects (ES Modules)

{
 "compilerOptions": {
 "target": "ES2022",
 "module": "ES2022",
 "moduleResolution": "node",
 "esModuleInterop": true,
 "strict": true,
 "noImplicitAny": true,
 "strictNullChecks": true,
 "noUnusedLocals": true,
 "noUnusedParameters": true,
 "lib": ["ES2022"],
 "skipLibCheck": true,
 "forceConsistentCasingInFileNames": true,
 "outDir": "dist",
 "rootDir": "src",
 "declaration": true,
 "resolveJsonModule": true
 },
 "include": ["src/**/*.ts"],
 "exclude": ["node_modules", "dist"]
}

For Node.js/Backend Projects (CommonJS)

{
 "compilerOptions": {
 "target": "ES2020",
 "module": "CommonJS",
 "outDir": "./dist",
 "rootDir": "./src",
 "strict": true,
 "esModuleInterop": true,
 "skipLibCheck": true,
 "forceConsistentCasingInFileNames": true,
 "resolveJsonModule": true
 },
 "include": ["src/**/*"],
 "exclude": ["node_modules"]
}

When to use CommonJS:

Legacy Node.js projects
Enterprise environments with older Node versions
Projects that depend on CommonJS-only packages
When ES modules cause compatibility issues

2. Linting and Formatting

Option A: Biome (Recommended)

Configuration (biome.json):

{
 "$schema": "https://biomejs.dev/schemas/1.9.4/schema.json",
 "organizeImports": {
 "enabled": true
 },
 "formatter": {
 "enabled": true,
 "indentStyle": "space",
 "indentWidth": 2,
 "lineWidth": 120,
 "lineEnding": "lf"
 },
 "linter": {
 "enabled": true,
 "rules": {
 "recommended": true,
 "suspicious": {
 "noExplicitAny": "warn"
 },
 "style": {
 "useConst": "error",
 "noNonNullAssertion": "warn"
 }
 }
 },
 "javascript": {
 "formatter": {
 "quoteStyle": "single",
 "semicolons": "asNeeded",
 "trailingCommas": "es5"
 }
 },
 "files": {
 "ignore": [
 "dist",
 "node_modules",
 "test-results",
 "playwright-report",
 "*.config.js",
 "*.config.ts"
 ]
 }
}

Package.json scripts:

{
 "scripts": {
 "lint": "biome check .",
 "lint:fix": "biome check --write .",
 "format": "biome format --write .",
 "check": "biome check . && tsc --noEmit"
 }
}

Dependencies:

npm install --save-dev @biomejs/biome

Biome advantages:

10-100x faster than ESLint (Rust-based)
Single tool for linting + formatting + import sorting
Zero config needed (sensible defaults)
Simple configuration file
Modern, actively developed

Code style:

Single quotes
Semicolons only when needed (ASI-friendly)
Trailing commas in ES5 contexts (arrays, objects)
120 character line width
2-space indentation

Option B: ESLint + Prettier (Traditional)

ESLint Configuration (eslint.config.js):

import eslint from '@eslint/js'
import tseslint from '@typescript-eslint/eslint-plugin'
import tsParser from '@typescript-eslint/parser'

export default [
 eslint.configs.recommended,
 {
 files: ['**/*.ts', '**/*.js'],
 languageOptions: {
 parser: tsParser,
 ecmaVersion: 2020,
 sourceType: 'module',
 globals: {
 // Browser globals
 window: 'readonly',
 document: 'readonly',
 console: 'readonly',
 // Node globals
 process: 'readonly',
 module: 'readonly',
 require: 'readonly',
 __dirname: 'readonly'
 }
 },
 plugins: {
 '@typescript-eslint': tseslint
 },
 rules: {
 ...tseslint.configs.recommended.rules,
 '@typescript-eslint/no-unused-vars': ['error', {
 argsIgnorePattern: '^_',
 varsIgnorePattern: '^_'
 }],
 '@typescript-eslint/no-explicit-any': 'warn',
 'no-console': 'warn',
 'semi': ['error', 'never'],
 'quotes': ['error', 'single', { avoidEscape: true }],
 'comma-dangle': ['error', 'never']
 }
 },
 {
 files: ['**/*.test.js', '**/*.test.ts'],
 rules: {
 'no-console': 'off'
 }
 }
]

Prettier Configuration (.prettierrc.json):

{
 "semi": false,
 "singleQuote": true,
 "trailingComma": "none",
 "printWidth": 100,
 "tabWidth": 2,
 "arrowParens": "avoid"
}

Package.json scripts:

{
 "scripts": {
 "lint": "eslint src/**/*.{js,ts}",
 "lint:fix": "eslint src/**/*.{js,ts} --fix",
 "lint:errors-only": "eslint src/**/*.{js,ts} --quiet",
 "format": "prettier --write src/**/*.{js,ts}",
 "format:check": "prettier --check src/**/*.{js,ts}",
 "check": "npm run typecheck && npm run lint && npm run format:check"
 }
}

Dependencies:

npm install --save-dev \
 eslint @eslint/js \
 @typescript-eslint/eslint-plugin \
 @typescript-eslint/parser \
 prettier

Code style:

Single quotes
No semicolons
No trailing commas
100 character line width
2-space indentation

Option C: No Linting (Minimal)

When to use:

Small, simple projects
Relying on TypeScript strict mode for type safety
Team has strong IDE setup and conventions
CI handles quality checks

Package.json scripts:

{
 "scripts": {
 "check": "tsc --noEmit"
 }
}

Note: TypeScript's strict mode catches many issues that linters would, but you lose style consistency enforcement.

3. Testing Configurations

Option A: Vitest Only

When to use: Unit testing, integration testing, API testing (no browser needed).

Configuration (vitest.config.js):

import {defineConfig} from 'vitest/config'

export default defineConfig({
 test: {
 environment: 'jsdom',
 globals: true,
 setupFiles: ['./tests/setup.js'],
 include: ['./tests/**/*.test.js', './tests/**/*.test.ts', './tests/**/*.spec.ts'],
 coverage: {
 provider: 'v8',
 reporter: ['text', 'json', 'html']
 }
 }
})

Note: Vitest works without a config file - it will auto-discover tests. Config is optional for customization.

Package.json scripts:

{
 "scripts": {
 "test": "vitest run",
 "test:watch": "vitest",
 "test:coverage": "vitest run --coverage",
 "test:ui": "vitest --ui"
 }
}

Dependencies:

npm install --save-dev vitest @vitest/coverage-v8

Option B: Playwright Only

When to use: E2E testing, browser testing, visual testing.

Configuration (playwright.config.ts):

import { defineConfig, devices } from '@playwright/test'

export default defineConfig({
 testDir: './tests',
 fullyParallel: true,
 forbidOnly: !!process.env.CI,
 retries: process.env.CI ? 2 : 0,
 workers: process.env.CI ? 1 : undefined,
 reporter: 'html',

 use: {
 baseURL: process.env.BASE_URL || 'http://localhost:3000',
 trace: 'on-first-retry',
 screenshot: 'only-on-failure',
 },

 projects: [
 {
 name: 'chromium',
 use: { ...devices['Desktop Chrome'] },
 },
 ],

 webServer: process.env.BASE_URL ? undefined : {
 command: 'npm run preview',
 url: 'http://localhost:3000',
 reuseExistingServer: !process.env.CI,
 },
})

Package.json scripts:

{
 "scripts": {
 "test": "playwright test",
 "test:headed": "playwright test --headed",
 "test:ui": "playwright test --ui"
 }
}

Dependencies:

npm install --save-dev @playwright/test

Option C: Vitest + Playwright

When to use: Comprehensive testing strategy (fast unit tests + thorough E2E tests).

Testing strategy:

```
.test.ts
```
files → Vitest (unit tests)
```
.spec.ts
```
files → Playwright (E2E tests)

Package.json scripts:

{
 "scripts": {
 "test": "vitest run",
 "test:watch": "vitest",
 "test:coverage": "vitest run --coverage",
 "test:ui": "vitest --ui",
 "test:e2e": "playwright test",
 "test:e2e:ui": "playwright test --ui",
 "test:e2e:report": "playwright show-report"
 }
}

4. Pre-commit Hooks with Husky

Setup Husky:

npm install --save-dev husky
npx husky init

Pre-commit hook (.husky/pre-commit):

#!/usr/bin/env sh
. "$(dirname -- "$0")/_/husky.sh"

npm run quality:commit

Package.json scripts:

For Biome:

{
 "scripts": {
 "quality": "npm run check && npm run test",
 "quality:commit": "biome check . && tsc --noEmit && npm run test",
 "prepare": "husky"
 }
}

For ESLint+Prettier:

{
 "scripts": {
 "quality": "npm run typecheck && npm run lint && npm run format:check && npm run test",
 "quality:commit": "npm run typecheck && npm run lint:errors-only && npm run test",
 "prepare": "husky"
 }
}

For minimal (no linting):

{
 "scripts": {
 "quality": "npm run typecheck && npm run test",
 "quality:commit": "tsc --noEmit && npm run test",
 "prepare": "husky"
 }
}

What runs in pre-commit:

Type checking (fast)
Linting errors only (warnings ignored)
Tests (unit tests only, not E2E)

What NOT to run in pre-commit:

Formatting (too slow, should be editor responsibility)
Full linting with warnings (too noisy)
E2E tests (too slow)

5. Makefile

Common Makefile targets:

.PHONY: help install build test clean lint format check

help:
 @echo "Available targets:"
 @echo " install - Install dependencies"
 @echo " build - Build the project"
 @echo " test - Run tests"
 @echo " clean - Clean build artifacts"
 @echo " lint - Run linting"
 @echo " format - Format code"
 @echo " check - Run all quality checks"

install:
 npm ci

build:
 npm run build

test:
 npm run test

clean:
 rm -rf dist node_modules

lint:
 npm run lint

format:
 npm run format

check:
 npm run quality

6. GitHub Actions

Basic CI workflow (.github/workflows/checks.yml):

name: Checks

on:
 push:
 branches-ignore:
 - main
 pull_request:
 branches:
 - main

permissions: read-all

jobs:
 quality:
 runs-on: ubuntu-latest
 steps:
 - uses: actions/checkout@v4

 - name: Setup Node.js
 uses: actions/setup-node@v4
 with:
 node-version: '20'
 cache: 'npm'

 - name: Install dependencies
 run: npm ci

 - name: Type check
 run: npm run typecheck

 - name: Lint
 run: npm run lint
 if: hashFiles('biome.json', 'eslint.config.js') != ''

 - name: Test
 run: npm run test
 if: hashFiles('vitest.config.js', 'playwright.config.ts') != ''

7. Complete Package.json Examples

For ES Modules + Biome + Vitest:

{
 "name": "my-typescript-project",
 "version": "1.0.0",
 "type": "module",
 "scripts": {
 "dev": "your-dev-command",
 "build": "tsc",
 "typecheck": "tsc --noEmit",
 "test": "vitest run",
 "test:watch": "vitest",
 "test:coverage": "vitest run --coverage",
 "lint": "biome check .",
 "lint:fix": "biome check --write .",
 "format": "biome format --write .",
 "check": "biome check . && tsc --noEmit",
 "quality": "npm run check && npm run test",
 "quality:commit": "biome check . && tsc --noEmit && npm run test",
 "prepare": "husky"
 },
 "devDependencies": {
 "@biomejs/biome": "^1.9.0",
 "@types/node": "^22.0.0",
 "@vitest/coverage-v8": "^2.1.0",
 "husky": "^9.0.0",
 "typescript": "^5.6.0",
 "vitest": "^2.1.0"
 }
}

For CommonJS + No Linting + Vitest:

{
 "name": "my-typescript-project",
 "version": "1.0.0",
 "scripts": {
 "build": "tsc",
 "test": "vitest",
 "coverage": "vitest run --coverage",
 "typecheck": "tsc --noEmit",
 "quality": "npm run typecheck && npm run test",
 "quality:commit": "tsc --noEmit && npm run test",
 "prepare": "husky"
 },
 "devDependencies": {
 "@types/node": "^22.0.0",
 "@vitest/coverage-v8": "^2.1.0",
 "husky": "^9.0.0",
 "typescript": "^5.6.0",
 "vitest": "^2.1.0"
 }
}

Quick Setup Guide

1. Initialize Project

npm init -y
npm install --save-dev typescript

2. Choose Module System

For ES Modules (recommended):

npm pkg set type=module

For CommonJS:

No action needed (default)

3. Initialize TypeScript

npx tsc --init

Then replace with the appropriate config from this skill.

4. Choose Linting/Formatting

Option A: Biome (recommended)

npm install --save-dev @biomejs/biome
npx @biomejs/biome init

Option B: ESLint + Prettier

npm install --save-dev \
 eslint @eslint/js \
 @typescript-eslint/eslint-plugin \
 @typescript-eslint/parser \
 prettier

Option C: None

Skip this step

5. Choose Testing

Option A: Vitest

npm install --save-dev vitest @vitest/coverage-v8

Option B: Playwright

npm init playwright@latest

Option C: Both

npm install --save-dev vitest @vitest/coverage-v8 @playwright/test
npm init playwright@latest

6. Set up Pre-commit Hooks

npm install --save-dev husky
npx husky init
echo "npm run quality:commit" > .husky/pre-commit
chmod +x .husky/pre-commit

7. Create Makefile

Create a

Makefile

with the targets shown above.

8. Set up GitHub Actions

Create

.github/workflows/checks.yml

with the workflow shown above.

Best Practices

1. Module System Choice

ES Modules (recommended for new projects):

Modern, future-proof
Better tree-shaking in bundlers
Native browser support
Required for Vite and modern tools

CommonJS (for legacy compatibility):

Better compatibility with older Node.js
Some npm packages only support CommonJS
Traditional Node.js pattern

2. Type Safety

Enable all strict flags in tsconfig.json
Use
```
noUnusedLocals
```
and
```
noUnusedParameters
```
Avoid
```
any
```
types (linters warn about them)
Prefix unused variables with
```
_
```
if needed

3. Code Style

Biome default: Single quotes, semicolons as needed, trailing commas in ES5 contexts
ESLint+Prettier default: Single quotes, no semicolons, no trailing commas
Consistent 2-space indentation
120 char line width (modern)

4. Testing Strategy

Vitest only: Fast, good for libraries and backend
Playwright only: Essential for frontend apps
Both: Comprehensive coverage for full-stack apps
Keep E2E tests out of pre-commit hooks (too slow)

5. Pre-commit Hooks

Run fast checks only (typecheck, lint errors, unit tests)
Skip slow checks (formatting, warnings, E2E tests)
Let CI handle comprehensive quality checks
Developers should format code via editor

6. CI/CD

Run comprehensive checks in CI (what you skip in pre-commit)
Use caching for faster builds
Separate workflows for PRs vs main branch
Consider coverage thresholds

7. Makefile Usage

Provides consistent interface across projects
Easier for new contributors (single command reference)
Works regardless of language/tooling
Good for complex multi-step operations

Decision Matrix

Criteria	Biome	ESLint+Prettier	None
Speed	Much faster	Slower	Fastest
Simplicity	Single tool	Two tools	No tools
Ecosystem	Growing	Mature, extensive	N/A
Style enforcement	Excellent	Excellent	Manual
Type safety	Via rules	Via rules	TypeScript only