Quick Start

Get up and running with the AI-Enhanced TypeScript Template in minutes! This guide will walk you through the development workflow and show you how to integrate Task Master AI and Augment Code for enhanced productivity.

First Steps

After installation, you should have a project directory with all dependencies installed. Let's verify everything works:

# Navigate to your project (if not already there)
cd my-project

# Verify the setup
npm run check

This runs our comprehensive quality gates: linting, formatting, and testing. If everything passes, you're ready to go! ✅

Enhanced Development Workflow

1. Start Development

The fastest way to start developing is with tsx, which runs TypeScript directly:

# Start development with tsx (recommended)
npm run dev:tsx

2. Optional: Initialize Task Master AI

If you want to use AI-powered project management (requires separate installation):

# Initialize Task Master AI for your project
task-master init --name="My Project" --description="TypeScript application"

# Configure AI models for development assistance
task-master models --setup

You should see output like:

2024-01-15 14:30:00 [INFO]: 🚀 Starting TypeScript Template v1.0.0
2024-01-15 14:30:00 [INFO]: ✅ Configuration validation passed
2024-01-15 14:30:00 [INFO]: ✅ User input validated successfully
2024-01-15 14:30:00 [INFO]: ✅ Application completed successfully

2. Auto-Restart Development

For continuous development with automatic restarts on file changes:

# Start with auto-restart
npm run dev:watch

Now edit src/index.ts and watch the application restart automatically!

3. Auto-Restart Development

For continuous development with automatic restarts on file changes:

# Start with auto-restart
npm run dev:watch

4. Optional: AI-Powered Task Management

If you've set up Task Master AI, you can use it for project management:

# Generate tasks from requirements (if you have a PRD)
task-master parse-prd --input=docs/requirements.md --num-tasks=10

# View all tasks
task-master list

# Get next recommended task
task-master next

# Update task status as you work
task-master set-status --id=1 --status=done

5. Traditional Build & Run

If you prefer the traditional compile-then-run approach:

# Build and run
npm run dev

# Or step by step
npm run build
npm start

Making Your First Changes

Let's modify the template to make it your own:

1. Update Package Information

Edit package.json:

{
  "name": "my-awesome-project",
  "version": "0.1.0",
  "description": "My awesome TypeScript project",
  // ... rest of the configuration
}

2. Modify the Main Function

Edit src/index.ts to use validation and logging:

import { logger, loggerUtils } from './logger.js';
import { validateUserInput } from './validation.js';
import { delay } from './utils.js';

export async function main(): Promise<void> {
  loggerUtils.logStartup(logger, 'My Awesome Project', '0.1.0');

  // Example: Validate user input
  const userData = {
    name: 'John Doe',
    email: 'john@example.com',
    age: 30
  };

  const result = validateUserInput(userData);
  if (result.success) {
    loggerUtils.logValidationSuccess(logger, 'User data validated', result.data);
  } else {
    loggerUtils.logValidationFailure(logger, 'Invalid user data', result.error);
    return;
  }

  // Your application logic here
  await delay(100);

  loggerUtils.logCompletion(logger, 'Application completed successfully');
}

3. Add Your Own Utilities

Edit src/utils.ts or create new files with proper validation:

import { z } from 'zod';
import { logger } from './logger.js';

// Define a schema for your custom function
const ProcessInputSchema = z.object({
  text: z.string().min(1, 'Text cannot be empty'),
  options: z.object({
    uppercase: z.boolean().default(false),
    prefix: z.string().default('')
  }).optional()
});

/**
 * Your custom utility function with validation.
 */
export function myCustomFunction(input: unknown): string {
  const result = ProcessInputSchema.safeParse(input);

  if (!result.success) {
    logger.error('Invalid input for myCustomFunction', {
      error: result.error.message
    });
    throw new Error(`Invalid input: ${result.error.message}`);
  }

  const { text, options = {} } = result.data;
  let processed = options.prefix ? `${options.prefix}${text}` : text;

  if (options.uppercase) {
    processed = processed.toUpperCase();
  }

  logger.debug('Processed input', { input: text, output: processed });
  return `Processed: ${processed}`;
}

4. Write Tests

Add tests in __tests__/ with proper mocking:

import { jest } from '@jest/globals';
import { myCustomFunction } from '../src/utils.js';

// Mock the logger
jest.mock('../src/logger.js', () => ({
  logger: {
    error: jest.fn(),
    debug: jest.fn(),
    info: jest.fn(),
    warn: jest.fn()
  }
}));

describe('myCustomFunction', () => {
  it('should process input correctly', () => {
    const input = { text: 'test' };
    const result = myCustomFunction(input);
    expect(result).toBe('Processed: test');
  });

  it('should handle validation errors', () => {
    expect(() => myCustomFunction({ text: '' })).toThrow('Invalid input');
  });

  it('should apply options correctly', () => {
    const input = {
      text: 'test',
      options: { uppercase: true, prefix: 'PREFIX_' }
    };
    const result = myCustomFunction(input);
    expect(result).toBe('Processed: PREFIX_TEST');
  });
});

Validation and Logging Features

The template includes powerful validation and logging capabilities:

Input Validation with Zod

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

// Validate user input
const userResult = validateUserInput({
  name: 'John Doe',
  email: 'john@example.com',
  age: 30
});

if (userResult.success) {
  // Use validated data with full TypeScript typing
  const user = userResult.data;
  console.log(`Welcome, ${user.name}!`);
} else {
  console.error('Validation failed:', userResult.error);
}

Professional Logging with Winston

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

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

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

Configuration Management

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();
  }
}

Essential Commands

Here are the commands you'll use most frequently:

Development

# Fast development (recommended)
npm run dev:tsx

# Development with auto-restart
npm run dev:watch

# Traditional build and run
npm run dev

Quality Assurance

# Run all quality checks
npm run check

# Auto-fix issues
npm run fix

# Individual checks
npm run lint
npm run format:check
npm test

Building

# Build for production
npm run build

# Clean build artifacts
npm run clean

# Run the built application
npm start

Project Structure Overview

Here's what you're working with:

my-project/
├── src/                    # Your source code
│   ├── index.ts           # Main entry point
│   └── utils.ts           # Utility functions
├── __tests__/             # Test files
│   ├── index.test.ts      # Main function tests
│   └── utils.test.ts      # Utility tests
├── dist/                  # Build output (generated)
├── docs/                  # Documentation (Docusaurus)
├── package.json           # Project configuration
├── tsconfig.json          # TypeScript config
├── eslint.config.js       # ESLint config
├── jest.config.js         # Jest config
└── README.md              # Project README

Quality Gates

The template includes comprehensive quality gates that run automatically:

Linting (ESLint)

• TypeScript-specific rules
• Code quality enforcement
• Import organization
• Prettier integration

Formatting (Prettier)

• Consistent code style
• Automatic formatting
• Integration with ESLint

Testing (Jest)

• TypeScript support
• ES modules compatibility
• Coverage reporting
• Async testing patterns

Building (TypeScript)

• Strict type checking
• Declaration file generation
• Source map generation
• Clean output

Next Steps

Now that you have the basics working:

1. Understand the Project Structure - Learn about each file and directory
2. Development Workflow - Deep dive into the development process
3. Testing Guide - Learn testing patterns and best practices
4. Configuration - Customize the template for your needs

Tips for Success

🚀 Use tsx for Development

It's the fastest way to iterate - no compilation step needed!

✅ Run Quality Checks Early

Use npm run check frequently to catch issues before they become problems.

🔄 Leverage Auto-Fix

Use npm run fix to automatically resolve formatting and fixable linting issues.

📝 Write Tests

The template makes testing easy - write tests as you develop!

📚 Document Your Code

Use TSDoc comments for all exported functions - the template shows you how.

Happy coding with enhanced TypeScript development! 🚀🤖