TypeScript Project Template API

AI-Enhanced TypeScript Template

A comprehensive TypeScript project template designed for modern development workflows with integrated Task Master AI and Augment Code support. This template provides the foundation, configurations, and guidelines needed to leverage AI-powered project management and intelligent development assistance effectively.

🚀 Enhanced Development Features

🤖 Task Master AI Ready - Pre-configured for Task Master AI integration with setup guides and best practices
🧠 Augment Code Optimized - Project structure and patterns designed to work effectively with AI development tools
⚡ Streamlined Workflow - Configurations that support seamless integration between AI project management and coding assistance
🎯 Quality-First Approach - Comprehensive linting, testing, and formatting with AI-friendly code patterns
✅ Input Validation - Zod schemas for type-safe runtime validation with detailed error reporting
📝 Professional Logging - Winston logging system with structured output and configurable levels
⚙️ Configuration Management - Type-safe configuration loading with validation and feature flags
📊 Documentation Tools - VitePress and TypeDoc setup for automated API documentation generation
🔒 Security Best Practices - Built-in security guidelines and dependency management workflows
⚙️ Modern TypeScript Foundation - TypeScript 5.5+, ESLint 9, Jest, and comprehensive development tooling

🚀 Quick Start

bash

# Clone the template
git clone https://github.com/almai/typescript-augment-setup.git my-project
cd my-project

# Install dependencies
npm install

# Start development
npm run dev:tsx

# Run quality checks
npm run check

# Optional: Set up Task Master AI (requires separate installation)
task-master init --name="My Project" --description="TypeScript application"
task-master models --setup

# Optional: Generate tasks from requirements
task-master parse-prd --input=docs/requirements.md --num-tasks=10

Available Scripts

Development

npm run dev:tsx - Run TypeScript directly with tsx (fastest)
npm run dev:watch - Run with auto-restart on file changes
npm run dev - Build and run (traditional approach)

Quality Assurance

npm run check - Run all quality checks (lint + format + test)
npm run fix - Auto-fix linting and formatting issues
npm run lint - Run ESLint
npm run lint:fix - Fix auto-fixable ESLint issues
npm run format - Format code with Prettier
npm run format:check - Check if code is properly formatted

Testing

npm test - Run Jest tests
npm run test:watch - Run tests in watch mode
npm run test:coverage - Run tests with coverage report
npm run test:ci - Run tests for CI/CD

Build & Production

npm run build - Build for production
npm run clean - Clean build artifacts
npm start - Run built application

AI-Enhanced Documentation & Intelligence

npm run docs:dev - Start VitePress development server with AI-generated content
npm run docs:build - Build documentation for production with automated API docs
npm run docs:preview - Preview built documentation locally
npm run docs:api - Generate TypeDoc API documentation with AI-enhanced descriptions

Dependencies

npm run deps:check - Check for dependency updates
npm run deps:update - Update dependencies

Project Structure

├── src/                    # Source code
│   ├── index.ts           # Main entry point with validation and logging examples
│   ├── validation.ts      # Zod schemas and validation functions
│   ├── logger.ts          # Winston logging configuration and utilities
│   ├── config.ts          # Configuration management with validation
│   └── utils.ts           # Utility functions
├── __tests__/             # Test files
│   ├── index.test.ts      # Main application tests
│   ├── validation.test.ts # Validation schema tests
│   ├── logger.test.ts     # Logging functionality tests
│   └── config.test.ts     # Configuration management tests
├── dist/                  # Build output (generated)
├── docs/                  # VitePress documentation source
│   ├── validation/        # Validation system documentation
│   ├── logging/           # Logging system documentation
│   ├── configuration/     # Configuration management docs
│   └── ...               # Other documentation sections
├── build/                 # VitePress build output (generated)
├── coverage/              # Test coverage reports (generated)
├── tsconfig.json          # TypeScript config for development
├── tsconfig.build.json    # TypeScript config for production builds
├── eslint.config.js       # ESLint configuration (flat config)
├── jest.config.js         # Jest configuration
├── jest.setup.js          # Jest setup file
├── .prettierrc.json       # Prettier configuration
└── package.json           # Project configuration

Configuration Details

TypeScript

Development: tsconfig.json with noEmit: true for IDE support
Production: tsconfig.build.json for actual compilation
Target: ES2022 for modern Node.js environments
Modules: ES modules with bundler resolution

ESLint

Version: ESLint 9 with flat configuration
TypeScript: Full TypeScript integration with type checking
Prettier: Integrated for consistent formatting
Jest: Special rules for test files
Import organization: Automatic import sorting and grouping

Jest

TypeScript: Full ES modules support with ts-jest
Coverage: 80% threshold for all metrics
Timeout: 30 seconds for async operations
Mocking: Global test utilities and console mocking

Prettier

Style: Single quotes, no trailing commas, 2-space indentation
Line width: 100 characters
Integration: Works seamlessly with ESLint

🤖 Enhanced Development Workflow

Project Setup: Standard TypeScript development with npm run dev:tsx
Quality Checks: npm run check for comprehensive linting, testing, and formatting
Optional AI Integration: Set up Task Master AI with task-master init for project management
Task Management: Use task-master parse-prd and task-master next for intelligent task breakdown
AI-Assisted Development: Leverage Augment Code for context-aware coding assistance
Progress Tracking: Update task status with task-master set-status as you work
Documentation: npm run docs:build for automated API documentation generation

🧠 AI-Enhanced Development Template

This TypeScript template is designed to work seamlessly with Task Master AI and Augment Code, providing the optimal project structure, configurations, and guidelines to leverage AI-powered development tools effectively. The template includes everything needed to get started with intelligent project management and AI-assisted coding.

🚀 Augment Code Integration

This template is optimized for Augment Code, an AI development platform featuring:

Advanced context engine: Retrieval and embedding capabilities for understanding code snippets across your codebase
Real-time codebase indexing: Maintains current understanding of project structure, dependencies, and code patterns
Multi-language support: Code assistance across TypeScript, JavaScript, and related technologies
Intelligent code generation: AI assistance that understands your project's architecture and coding standards

AI Development Guidelines (`.augment-guidelines`)

The template includes a comprehensive .augment-guidelines file that serves as the definitive guide for AI agents working on TypeScript/Node.js projects. This file provides:

Project awareness requirements: Guidelines for understanding codebase context and existing patterns
Code quality standards: ESLint, Prettier, and testing requirements with specific thresholds
Development workflow practices: Task management, git workflow, and quality gates
Security guidelines: Input validation, dependency management, and secure coding practices
TypeScript best practices: Modern patterns, error handling, and performance optimization
AI behavior rules: Communication patterns, error recovery, and tool coordination

The guidelines ensure consistent, high-quality code generation while maintaining project standards and architectural integrity.

🤖 Task Master AI Integration

This template includes setup guides and configurations for Task Master AI, an AI-powered project management tool that enhances how you plan, track, and execute development projects.

Installation

Task Master is installed globally and provides comprehensive project management capabilities:

bash

# Verify installation
task-master --help

# Check version
task-master --version

Quick Start

Initialize Task Master in your project:

bash

task-master init --name="My Project" --description="Project description"

Configure AI models:
bash
```
task-master models --setup
```
1
Generate tasks from a PRD (Product Requirements Document):
bash
```
task-master parse-prd --input=docs/prd.txt --num-tasks=10
```
1

View and manage tasks:

bash

# List all tasks
task-master list

# Show next task to work on
task-master next

# View specific task details
task-master show <task-id>

# Update task status
task-master set-status --id=<task-id> --status=done

Key Features

AI-powered task generation from PRD documents
Intelligent task breakdown and subtask management
Dependency tracking and workflow optimization
Progress tracking with multiple status types
Complexity analysis and expansion recommendations
Integration with AI models (Claude, GPT, etc.)

Task Management Commands

bash

# Task Creation & Management
task-master add-task --prompt="Add user authentication"
task-master update-task --id=1 --prompt="Updated requirements"
task-master remove-task --id=1

# Subtask Management
task-master add-subtask --parent=1 --title="Create login form"
task-master expand --id=1 --num=5  # Break task into subtasks

# Dependencies
task-master add-dependency --id=2 --depends-on=1
task-master validate-dependencies

# Analysis & Reporting
task-master analyze-complexity --threshold=5
task-master complexity-report

Configuration

Task Master uses these configuration files:

.taskmaster/config.json - AI model configuration
.taskmaster/tasks/tasks.json - Task data
.env - API keys (ANTHROPIC_API_KEY, etc.)

🔄 Integrated AI Development Workflow

The combination of Augment Code and Task Master AI creates an enhanced development experience:

1. Project Planning & Setup

bash

# Initialize Task Master for project management (requires separate installation)
task-master init --name="My Project" --description="TypeScript application"

# Configure AI models for task generation
task-master models --setup

# Generate initial tasks from requirements
task-master parse-prd --input=docs/requirements.md --num-tasks=15

2. Enhanced Development

Augment Code provides intelligent code assistance with codebase context
Task Master breaks down complex features into manageable, trackable tasks
Template guidelines ensure consistent quality and architectural patterns
Quality gates maintain code standards throughout development

3. Development Integration

bash

# Check next task to work on
task-master next

# Develop with AI assistance (Augment Code provides context-aware suggestions)
# Quality checks are enforced via template configurations

# Update task progress
task-master set-status --id=<task-id> --status=done

# Generate documentation and maintain project structure
npm run docs:api && npm run docs:build

4. Quality Assurance & Deployment

Automated testing with comprehensive coverage requirements
Security validation with dependency auditing and input validation
Performance optimization following template best practices
Documentation generation with TypeDoc and VitePress integration

🎯 AI-Enhanced Development Benefits

This template enables:

🚀 Accelerated Development: Integration with AI-powered code generation and task management tools
🎯 Consistent Quality: Automated enforcement of coding standards and best practices
🧠 Intelligent Context: Project structure optimized for AI tools to understand your codebase
📊 Project Visibility: Support for comprehensive task tracking and progress monitoring
🔒 Security-First: Built-in security guidelines and vulnerability management workflows
📚 Documentation-Ready: Automated documentation generation and maintenance tools

For detailed information:

Task Master AI: GitHub Repository
Augment Code: Platform Documentation
Template Guidelines: See .augment-guidelines file in project root

✅ Input Validation with Zod

The template includes a comprehensive validation system using Zod for runtime type safety and detailed error reporting.

Key Features

Type-safe validation with automatic TypeScript type inference
Detailed error messages with field-level validation feedback
Custom ValidationError class with structured error information
Pre-built schemas for common use cases (user input, configuration, server setup)
Result-type patterns for consistent error handling

Quick Example

typescript

import { validateUserInput } from './validation.js';

const result = validateUserInput({
  name: 'John Doe',
  email: 'john@example.com',
  age: 30
});

if (result.success) {
  // TypeScript knows the exact type
  const user = result.data;
  console.log(`Welcome, ${user.name}!`);
} else {
  // Handle validation errors
  console.error('Validation failed:', result.error);
}

Available Schemas

AppConfigSchema - Application configuration validation
UserInputSchema - User input validation with email, age, preferences
ServerConfigSchema - Server configuration with intelligent defaults

Documentation

Validation Overview - Complete validation system guide
Schema Reference - Detailed schema documentation
Usage Examples - Practical implementation examples
Error Handling - Error handling patterns
Custom Schemas - Creating your own schemas

📝 Professional Logging with Winston

The template includes a structured logging system using Winston for professional application logging.

Key Features

Structured logging with JSON output for production
Multiple log levels (error, warn, info, debug) with filtering
Configurable outputs (console with colors, file with JSON)
Logger utility functions for common logging patterns
Environment-aware configuration (development vs production)

Quick Example

typescript

import { logger, loggerUtils } from './logger.js';

// Structured logging
logger.info('User action performed', {
  userId: 123,
  action: 'login',
  timestamp: new Date().toISOString()
});

// Utility functions for common patterns
loggerUtils.logValidationSuccess(logger, 'Data validated', userData);
loggerUtils.logSectionHeader(logger, 'Processing Phase');
loggerUtils.logCompletion(logger, 'Operation completed successfully');

Configuration

typescript

import { createLogger } from './logger.js';

// Environment-specific configuration
const logger = createLogger({
  level: 'info',                    // Log level
  outputFile: 'logs/app.log',      // File output (null for console only)
  includeTimestamp: true,          // Include timestamps
  useColors: false                 // Colored output (console only)
});

Documentation

Logging Overview - Complete logging system guide
Configuration - Logger setup and options
Utilities - Utility functions and patterns
Best Practices - Professional logging guidelines
Migration Guide - Migrating from console.log

⚙️ Configuration Management

Type-safe configuration loading and validation with the ConfigManager class.

Key Features

Type-safe configuration with Zod validation
Environment-specific configs (development, production, test)
Feature flags for conditional functionality
Error handling for missing or invalid configuration files
Hot-reloadable configuration for runtime adjustments

Quick Example

typescript

import { ConfigManager } from './config.js';

const configManager = new ConfigManager();
const result = configManager.loadConfig();

if (result.success) {
  const serverConfig = configManager.getServerConfig();
  const logger = createLoggerFromConfig(configManager.getLoggingConfig());

  // Check feature flags
  if (configManager.isFeatureEnabled('enableMetrics')) {
    setupMetrics();
  }
}

Documentation

ConfigManager Guide - Complete configuration management
Validation - Configuration validation patterns

🏆 Development Best Practices

Code Quality & Standards

TSDoc documentation: Write comprehensive comments for all exported functions to help AI understand intent
Import organization: Follow established patterns (builtin → external → internal) for better AI code analysis
Test coverage: Maintain above 80% coverage with comprehensive test suites for AI validation
Commit messages: Use descriptive gitmoji-style messages for AI-powered project analysis
Quality gates: Run npm run check before committing to ensure AI-generated code meets standards

AI Development Workflow

Context awareness: Use Augment Code's codebase retrieval to understand existing patterns before making changes
Task-driven development: Break complex features into manageable tasks using Task Master
Iterative improvement: Use AI feedback loops to continuously improve code quality and architecture
Documentation-driven: Maintain up-to-date documentation to provide better context for AI assistance
Testing integration: Write comprehensive tests that AI can understand and extend

Project Organization

Modular architecture: Design deep modules with simple interfaces for better AI comprehension
Clear dependencies: Maintain explicit dependency relationships for AI-powered task management
Configuration management: Keep AI model configurations and guidelines up to date in .augment-guidelines
Security-first approach: Use input validation and dependency auditing as guided by AI security standards

Dependencies

Production

winston: Professional logging library with structured output and multiple transports
zod: TypeScript-first schema validation library for runtime type safety

Development Tools

TypeScript: Language and compiler (typescript)
ESLint: Linting with TypeScript support (eslint + plugins)
- @eslint/js: Core ESLint JavaScript rules
- @typescript-eslint/eslint-plugin: TypeScript-specific linting rules
- @typescript-eslint/parser: TypeScript parser for ESLint
- eslint-config-prettier: Disables ESLint rules that conflict with Prettier
- eslint-import-resolver-typescript: TypeScript import resolution for ESLint
- eslint-plugin-import: Import/export syntax linting
- eslint-plugin-jest: Jest-specific linting rules
- eslint-plugin-prettier: Runs Prettier as an ESLint rule
Prettier: Code formatting (prettier)
Jest: Testing framework (jest + supporting packages)
- @jest/globals: Jest global functions and types
- @types/jest: TypeScript definitions for Jest
- ts-jest: TypeScript preprocessor for Jest
TypeScript Support: Type definitions and tooling
- @types/node: Node.js type definitions
Development Utilities
- tsx: Fast TypeScript execution for development
- npm-check-updates: Dependency update management
Documentation
- vitepress: Modern documentation website generation
- typedoc: TypeScript API documentation generator
- typedoc-plugin-markdown: Markdown output plugin for TypeDoc

AI Development Integration

This template is optimized for use with:

Task Master AI: AI-powered task management system (requires separate installation via npm install -g task-master-ai)
Augment Code: AI development platform with advanced context engine
Development Guidelines: Comprehensive development standards defined in .augment-guidelines

🔧 Troubleshooting

Common Issues

Validation Errors

bash

# Check validation schema definitions
npm run dev:tsx  # Run application to see validation in action

# Test specific validation
node -e "
const { validateUserInput } = require('./dist/validation.js');
console.log(validateUserInput({ name: 'test', email: 'invalid' }));
"

Logging Issues

bash

# Check logger configuration
npm run dev:tsx  # Verify logging output format

# Test different log levels
LOG_LEVEL=debug npm run dev:tsx

Configuration Problems

bash

# Validate configuration file
node -e "
const { ConfigManager } = require('./dist/config.js');
const result = ConfigManager.validateConfigFile('./config.json');
console.log(result);
"

# Check configuration loading
npm run dev:tsx  # Application will show config validation results

TypeScript Compilation

bash

# Clear build cache
rm -rf dist/
npm run build

# Check TypeScript configuration
npx tsc --showConfig

Test Failures

bash

# Run specific test suites
npm test -- validation.test.ts
npm test -- logger.test.ts
npm test -- config.test.ts

# Clear Jest cache
npm test -- --clearCache

Performance Tips

Use npm run dev:tsx for fastest development iteration
Run npm run check before committing to catch issues early
Use structured logging instead of console.log for better performance
Validate input data early to prevent runtime errors
Configure appropriate log levels for different environments

License

This TypeScript template is provided as-is for creating modern TypeScript projects with AI development tool integration capabilities.

AI-Enhanced TypeScript Template ​

🚀 Enhanced Development Features ​

🚀 Quick Start ​

Available Scripts ​

Development ​

Quality Assurance ​

Testing ​

Build & Production ​

AI-Enhanced Documentation & Intelligence ​

Dependencies ​

Project Structure ​

Configuration Details ​

TypeScript ​

ESLint ​

Jest ​

Prettier ​

🤖 Enhanced Development Workflow ​

🧠 AI-Enhanced Development Template ​

🚀 Augment Code Integration ​

AI Development Guidelines (.augment-guidelines) ​

🤖 Task Master AI Integration ​

Installation ​

Quick Start ​

Key Features ​

Task Management Commands ​

Configuration ​

🔄 Integrated AI Development Workflow ​

1. Project Planning & Setup ​

2. Enhanced Development ​

3. Development Integration ​

4. Quality Assurance & Deployment ​

🎯 AI-Enhanced Development Benefits ​

✅ Input Validation with Zod ​

Key Features ​

Quick Example ​

Available Schemas ​

Documentation ​

📝 Professional Logging with Winston ​

Key Features ​

Quick Example ​

Configuration ​

Documentation ​

⚙️ Configuration Management ​

Key Features ​

Quick Example ​

Documentation ​

🏆 Development Best Practices ​

Code Quality & Standards ​

AI Development Workflow ​

Project Organization ​

Dependencies ​

Production ​

Development Tools ​

AI Development Integration ​

🔧 Troubleshooting ​

Common Issues ​

Validation Errors ​

Logging Issues ​

Configuration Problems ​

TypeScript Compilation ​

Test Failures ​

Performance Tips ​

License ​

AI-Enhanced TypeScript Template

🚀 Enhanced Development Features

🚀 Quick Start

Available Scripts

Development

Quality Assurance

Testing

Build & Production

AI-Enhanced Documentation & Intelligence

Dependencies

Project Structure

Configuration Details

TypeScript

ESLint

Jest

Prettier

🤖 Enhanced Development Workflow

🧠 AI-Enhanced Development Template

🚀 Augment Code Integration

AI Development Guidelines (`.augment-guidelines`)

🤖 Task Master AI Integration

Installation

Quick Start

Key Features

Task Management Commands

Configuration

🔄 Integrated AI Development Workflow

1. Project Planning & Setup

2. Enhanced Development

3. Development Integration

4. Quality Assurance & Deployment

🎯 AI-Enhanced Development Benefits

✅ Input Validation with Zod

Key Features

Quick Example

Available Schemas

Documentation

📝 Professional Logging with Winston

Key Features

Quick Example

Configuration

Documentation

⚙️ Configuration Management

Key Features

Quick Example

Documentation

🏆 Development Best Practices

Code Quality & Standards

AI Development Workflow

Project Organization

Dependencies

Production

Development Tools

AI Development Integration

🔧 Troubleshooting

Common Issues

Validation Errors

Logging Issues

Configuration Problems

TypeScript Compilation

Test Failures

Performance Tips

License