TypeScript Tooling Specialist

name: "TypeScript Tooling Specialist"
slug: "tooling-typescript-generator"
description: "Generate TypeScript/JavaScript project scaffolding with npm/pnpm/yarn, Jest/Vitest, ESLint/Prettier, and bundling (Vite/Rollup/esbuild)."
capabilities:
- Project structure generation (library, CLI, API, React/Vue frontend)
- Package manager setup (npm, pnpm, yarn with workspaces)
- Testing framework configuration (Jest, Vitest, Playwright)
- TypeScript configuration (strict mode, paths, decorators)
- Linting and formatting (ESLint, Prettier, Biome)
- Bundling and build tools (Vite, Rollup, esbuild, tsup)
- Monorepo setup (Turborepo, Nx)
inputs:
- project_type: "library | cli | api | react | vue | monorepo (string)"
- package_manager: "npm | pnpm | yarn (string)"
- typescript_version: "5.3 | 5.4 | 5.5 (string)"
- project_name: "Name of the project (string)"
outputs:
- project_structure: "Directory layout with all config files (JSON)"
- package_json: "Complete package.json configuration"
- tsconfig_json: "TypeScript configuration"
- build_config: "Vite/Rollup/esbuild configuration"
keywords:
- typescript
- javascript
- tooling
- npm
- jest
- vitest
- eslint
- vite
- node
- react
version: "1.0.0"
owner: "cognitive-toolworks"
license: "MIT"
security: "Public; no secrets or PII; safe for open repositories"
links:
- https://www.typescriptlang.org/docs/
- https://docs.npmjs.com/
- https://vitejs.dev/guide/
- https://jestjs.io/docs/getting-started
- https://eslint.org/docs/latest/

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
   json { "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
   json { "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
json { "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:
javascript 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
json { "devDependencies": { "vitest": "^1.6.0" }, "scripts": { "test": "vitest run", "test:watch": "vitest" } }

1. Linting and Formatting

ESLint + Prettier accessed 2025-10-26
json { "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:
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" } }

1. Build Tools

Vite (for libraries and apps) accessed 2025-10-26
```javascript
// 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
json { "scripts": { "build": "tsup src/index.ts --format cjs,esm --dts" } }

1. React/Vue Project Setup

React with Vite:
json { "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:
json { "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:
yaml # pnpm-workspace.yaml packages: - 'packages/*' - 'apps/*'

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

Turborepo accessed 2025-10-26
json { "devDependencies": { "turbo": "^2.0.0" } }

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

1. TypeScript Path Mapping
   json { "compilerOptions": { "baseUrl": ".", "paths": { "@/*": ["src/*"], "@utils/*": ["src/utils/*"], "@components/*": ["src/components/*"] } } }

2. CI/CD Pipeline (GitHub Actions)
   .github/workflows/ci.yml 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

3. Package Publishing accessed 2025-10-26
   json { "files": ["dist"], "exports": { ".": { "import": "./dist/index.js", "require": "./dist/index.cjs", "types": "./dist/index.d.ts" } }, "publishConfig": { "access": "public" } }

4. Playwright E2E Testing (for React/Vue)
   json { "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