TypeScript Tooling Specialist

Purpose & When-To-Use

Trigger conditions:

• Starting a new TypeScript/JavaScript project requiring modern tooling
• Migrating legacy JavaScript projects to TypeScript
• Setting up React/Vue applications with type safety
• Creating CLI tools with Node.js
• Building monorepo workspaces with shared packages

Not for:

• Next.js/Nuxt projects (use framework CLIs)
• React Native/Expo (use mobile-cicd-generator)
• Simple scripts without build requirements

Pre-Checks

Time normalization:

• Compute NOW_ET using NIST/time.gov semantics (America/New_York, ISO-8601)
• Use NOW_ET for all citation access dates

Input validation:

• project_type must be one of: library, cli, api, react, vue, monorepo
• package_manager must be one of: npm, pnpm, yarn
• typescript_version must be one of: 5.3, 5.4, 5.5
• project_name must be valid npm package name (lowercase, hyphens allowed)

Source freshness:

• TypeScript docs must be accessible accessed 2025-10-26
• npm docs must be accessible accessed 2025-10-26
• Vite docs must be accessible accessed 2025-10-26
• Jest docs must be accessible accessed 2025-10-26

Procedure

T1: Basic Project Structure (≤2k tokens)

Fast path for common cases:

1. Directory Layout Generation

   project-name/
     src/
       index.ts
     tests/
       index.test.ts
     package.json
     tsconfig.json
     .gitignore
     README.md
   

2. Core package.json accessed 2025-10-26

   {
     "name": "project-name",
     "version": "0.1.0",
     "type": "module",
     "main": "./dist/index.js",
     "types": "./dist/index.d.ts",
     "scripts": {
       "build": "tsc",
       "test": "jest",
       "lint": "eslint src"
     },
     "devDependencies": {
       "typescript": "^5.5.0",
       "@types/node": "^20.0.0"
     }
   }
   

3. TypeScript Configuration accessed 2025-10-26

   {
     "compilerOptions": {
       "target": "ES2022",
       "module": "ESNext",
       "moduleResolution": "bundler",
       "strict": true,
       "esModuleInterop": true,
       "skipLibCheck": true,
       "declaration": true,
       "outDir": "./dist"
     },
     "include": ["src"],
     "exclude": ["node_modules", "dist"]
   }
   

Decision: If only basic scaffolding needed → STOP at T1; otherwise proceed to T2.

T2: Full Tooling Setup (≤6k tokens)

Extended configuration with testing and build tools:

1. Testing Framework Configuration

   Jest accessed 2025-10-26

   {
     "devDependencies": {
       "jest": "^29.7.0",
       "@types/jest": "^29.5.0",
       "ts-jest": "^29.1.0"
     },
     "scripts": {
       "test": "jest",
       "test:watch": "jest --watch",
       "test:coverage": "jest --coverage"
     }
   }
   

   jest.config.js:

   export default {
     preset: 'ts-jest',
     testEnvironment: 'node',
     roots: ['<rootDir>/tests'],
     testMatch: ['**/*.test.ts'],
     collectCoverageFrom: ['src/**/*.ts'],
     coverageThreshold: {
       global: { branches: 80, functions: 80, lines: 80 }
     }
   };
   

   Vitest (alternative, faster) accessed 2025-10-26

   {
     "devDependencies": {
       "vitest": "^1.6.0"
     },
     "scripts": {
       "test": "vitest run",
       "test:watch": "vitest"
     }
   }
   

2. Linting and Formatting

   ESLint + Prettier accessed 2025-10-26

   {
     "devDependencies": {
       "eslint": "^8.57.0",
       "@typescript-eslint/parser": "^7.0.0",
       "@typescript-eslint/eslint-plugin": "^7.0.0",
       "prettier": "^3.2.0",
       "eslint-config-prettier": "^9.1.0"
     }
   }
   

   .eslintrc.json:

   {
     "parser": "@typescript-eslint/parser",
     "plugins": ["@typescript-eslint"],
     "extends": [
       "eslint:recommended",
       "plugin:@typescript-eslint/recommended",
       "prettier"
     ],
     "rules": {
       "@typescript-eslint/no-unused-vars": "error",
       "@typescript-eslint/explicit-function-return-type": "warn"
     }
   }
   

3. Build Tools

   Vite (for libraries and apps) accessed 2025-10-26

   // vite.config.ts
   import { defineConfig } from 'vite';
   import { resolve } from 'path';
   
   export default defineConfig({
     build: {
       lib: {
         entry: resolve(__dirname, 'src/index.ts'),
         name: 'MyLib',
         fileName: 'index'
       }
     }
   });
   

   tsup (zero-config bundler) accessed 2025-10-26

   {
     "scripts": {
       "build": "tsup src/index.ts --format cjs,esm --dts"
     }
   }
   

4. React/Vue Project Setup

   React with Vite:

   {
     "dependencies": {
       "react": "^18.3.0",
       "react-dom": "^18.3.0"
     },
     "devDependencies": {
       "@vitejs/plugin-react": "^4.3.0",
       "@types/react": "^18.3.0",
       "@types/react-dom": "^18.3.0"
     }
   }
   

   Vue with Vite:

   {
     "dependencies": {
       "vue": "^3.4.0"
     },
     "devDependencies": {
       "@vitejs/plugin-vue": "^5.0.0"
     }
   }
   

T3: Advanced Configuration (≤12k tokens)

Deep configuration for monorepos and production:

1. Monorepo Setup accessed 2025-10-26

   pnpm Workspaces:

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

   Root package.json:

   {
     "name": "monorepo",
     "private": true,
     "scripts": {
       "build": "pnpm -r build",
       "test": "pnpm -r test",
       "lint": "pnpm -r lint"
     }
   }
   

   Turborepo accessed 2025-10-26

   {
     "devDependencies": {
       "turbo": "^2.0.0"
     }
   }
   

   turbo.json:

   {
     "pipeline": {
       "build": {
         "dependsOn": ["^build"],
         "outputs": ["dist/**"]
       },
       "test": {
         "dependsOn": ["build"]
       }
     }
   }
   

2. TypeScript Path Mapping

   {
     "compilerOptions": {
       "baseUrl": ".",
       "paths": {
         "@/*": ["src/*"],
         "@utils/*": ["src/utils/*"],
         "@components/*": ["src/components/*"]
       }
     }
   }
   

3. CI/CD Pipeline (GitHub Actions)

   name: CI
   on: [push, pull_request]
   jobs:
     test:
       runs-on: ubuntu-latest
       steps:
         - uses: actions/checkout@v4
         - uses: pnpm/action-setup@v4
         - uses: actions/setup-node@v4
           with:
             node-version: 20
             cache: 'pnpm'
         - run: pnpm install --frozen-lockfile
         - run: pnpm test
         - run: pnpm build
   

4. Package Publishing accessed 2025-10-26

   {
     "files": ["dist"],
     "exports": {
       ".": {
         "import": "./dist/index.js",
         "require": "./dist/index.cjs",
         "types": "./dist/index.d.ts"
       }
     },
     "publishConfig": {
       "access": "public"
     }
   }
   

5. Playwright E2E Testing (for React/Vue)

   {
     "devDependencies": {
       "@playwright/test": "^1.45.0"
     },
     "scripts": {
       "test:e2e": "playwright test"
     }
   }
   

Decision Rules

Package Manager Selection:

• pnpm: Monorepos, disk space efficiency, strict dependency resolution
• yarn: Existing Yarn projects, plug'n'play mode
• npm: Default choice, ubiquitous, simple projects

Project Type Structure:

• library: Dual ESM/CJS output, type declarations, no bundled dependencies
• cli: Shebang, executable permissions, bundled dependencies
• api: Express/Fastify setup, middleware, error handling
• react/vue: Component structure, routing, state management
• monorepo: Workspace configuration, shared packages, build orchestration

Abort Conditions:

• Invalid project_name (uppercase, special chars) → error
• Conflicting configuration (React + Vue) → error
• Unsupported TypeScript version → error

Tool Version Selection:

• Use latest stable TypeScript 5.x
• Pin dev dependencies, use caret ranges for prod
• ESM-first module strategy

Output Contract

Schema (JSON):

{
  "project_name": "string",
  "project_type": "library | cli | api | react | vue | monorepo",
  "typescript_version": "string",
  "package_manager": "npm | pnpm | yarn",
  "structure": {
    "directories": ["string"],
    "files": {
      "path/to/file": "file content (string)"
    }
  },
  "commands": {
    "install": "string",
    "dev": "string",
    "build": "string",
    "test": "string",
    "lint": "string"
  },
  "next_steps": ["string"],
  "timestamp": "ISO-8601 string (NOW_ET)"
}

Required Fields:

• All fields mandatory
• File contents must be syntactically valid (JSON, TypeScript)
• Include inline comments explaining configuration choices

Examples

Quick Start: TypeScript Library (29 lines)

// examples/library-example.ts
export interface CalculationResult {
  value: number;
  timestamp: Date;
}

export class Calculator {
  private history: number[] = [];

  add(a: number, b: number): CalculationResult {
    const value = a + b;
    this.history.push(value);
    return { value, timestamp: new Date() };
  }

  multiply(a: number, b: number): CalculationResult {
    const value = a * b;
    this.history.push(value);
    return { value, timestamp: new Date() };
  }

  getHistory(): readonly number[] {
    return Object.freeze([...this.history]);
  }

  clear(): void { this.history = []; }
}

Additional Examples:

• CLI Tool: examples/cli-example.ts (28 lines) - shebang, args, file operations
• Express API: examples/api-example.ts (30 lines) - typed routes, middleware, error handling

Template Resources (see resources/)

• tsconfig-library.json / tsconfig-react.json / tsconfig-node.json
• package-library.json / package-cli.json / package-api.json
• jest.config.js - Jest testing configuration

Quality Gates

Token Budgets:

• T1: ≤2k tokens (basic structure + package.json + tsconfig)
• T2: ≤6k tokens (testing, linting, build tools, React/Vue)
• T3: ≤12k tokens (monorepos, CI/CD, publishing, E2E)

Safety:

• No hardcoded API keys or secrets
• .gitignore includes node_modules, dist, .env
• ESLint configured to catch security issues

Auditability:

• All configurations cite official documentation
• Version constraints explicit
• Generation timestamp included

Determinism:

• Same inputs → identical structure
• Versions pinned where appropriate
• No randomness in generation

Performance:

• T1 generation: <1 second
• T2 generation: <3 seconds
• T3 generation: <5 seconds

Resources

Official Documentation (accessed 2025-10-26):

1. TypeScript Handbook - Language reference
2. npm Documentation - Package management
3. Vite Guide - Build tool and dev server
4. Jest Getting Started - Testing framework
5. ESLint User Guide - Linting
6. pnpm Workspaces - Monorepo management
7. Turborepo Docs - Build orchestration

Build Tools:

• Rollup - Module bundler
• esbuild - Extremely fast bundler
• tsup - Zero-config TypeScript bundler

Testing:

• Vitest - Vite-native test framework
• Playwright - E2E testing

Best Practices:

• TypeScript Deep Dive - Best practices
• React TypeScript Cheatsheet - Patterns