Project Structure

Understanding the TypeScript Project Template's organization and file structure.

Overview

The template follows modern TypeScript and Node.js conventions with a clear separation of concerns:

my-project/
├── src/                    # 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
├── docs/                  # VitePress documentation
│   ├── .vitepress/        # VitePress configuration
│   ├── getting-started/   # Getting started guides
│   ├── api/               # API documentation
│   └── index.md           # Documentation homepage
├── dist/                  # Build output (generated)
├── coverage/              # Test coverage reports (generated)
├── .github/               # GitHub Actions workflows
│   └── workflows/         # CI/CD pipeline definitions
├── package.json           # Project configuration
├── tsconfig.json          # TypeScript config (development)
├── tsconfig.build.json    # TypeScript config (production)
├── eslint.config.js       # ESLint configuration
├── jest.config.js         # Jest configuration
├── .prettierrc.json       # Prettier configuration
└── README.md              # Project README

Source Code (src/)

src/index.ts

The main entry point demonstrating:

• Async/await patterns
• Utility function usage
• TSDoc documentation
• Modern ES modules

src/utils.ts

Utility functions showcasing:

• TypeScript interfaces and types
• Error handling patterns
• Function documentation
• Modern JavaScript features

Tests (__tests__/)

Test Organization

• Mirror structure: Tests mirror the src/ directory structure
• Naming convention: *.test.ts for test files
• Coverage: Each module has corresponding tests

Test Patterns

• Unit tests: Individual function testing
• Integration tests: Component interaction testing
• Async testing: Promise and async/await testing
• Mock usage: External dependency mocking

Configuration Files

TypeScript Configuration

tsconfig.json (Development)

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "strict": true,
    "noEmit": true
  },
  "include": ["src/**/*", "__tests__/**/*"]
}

tsconfig.build.json (Production)

{
  "extends": "./tsconfig.json",
  "compilerOptions": {
    "noEmit": false,
    "outDir": "dist",
    "declaration": true,
    "sourceMap": true
  },
  "exclude": ["__tests__/**/*"]
}

ESLint Configuration (eslint.config.js)

• Modern flat configuration (ESLint 9)
• TypeScript integration with type checking
• Prettier integration for formatting
• Import organization rules
• Test-specific rules for Jest files

Jest Configuration (jest.config.js)

• TypeScript support with ts-jest
• ES modules compatibility
• Coverage thresholds (80% minimum)
• Test environment setup

Prettier Configuration (.prettierrc.json)

• Consistent formatting rules
• Single quotes preference
• No trailing commas for clean syntax
• 2-space indentation for readability

Documentation (docs/)

VitePress Structure

docs/
├── .vitepress/
│   └── config.ts          # VitePress configuration
├── getting-started/       # User guides
├── development/           # Development guides
├── configuration/         # Configuration guides
├── api/                   # API reference
├── deployment/            # Deployment guides
└── index.md               # Homepage

Documentation Features

• Modern design with dark/light themes
• Search functionality built-in
• Mobile responsive layout
• GitHub integration with edit links
• Automatic deployment to GitHub Pages

Build Outputs

dist/ Directory

Generated by TypeScript compilation:

• JavaScript files (.js)
• Declaration files (.d.ts)
• Source maps (.js.map)

coverage/ Directory

Generated by Jest testing:

• HTML reports for browser viewing
• JSON data for CI/CD integration
• Coverage metrics by file and function

GitHub Integration

.github/workflows/

• ci.yml: Continuous integration pipeline
• deploy-docs.yml: Documentation deployment

CI/CD Features

• Multi-version testing (Node.js 18, 20)
• Quality gates (lint, format, test, build)
• Dependency auditing for security
• Automatic documentation deployment

Best Practices Demonstrated

File Organization

• Clear separation of source and tests
• Logical grouping by functionality
• Consistent naming conventions

Configuration Management

• Environment-specific configurations
• Shared base configurations
• Override patterns for different contexts

Documentation Structure

• Progressive disclosure from basic to advanced
• Cross-references between related topics
• Practical examples in every section

Customization Guidelines

Adding New Modules

1. Create source file in src/
2. Add corresponding test in __tests__/
3. Update documentation in docs/api/
4. Export from main entry point if needed

Modifying Configuration

1. Update base configuration files
2. Test changes with npm run check
3. Update documentation if needed
4. Commit changes with descriptive messages

Extending Documentation

1. Add new markdown files in appropriate docs/ subdirectory
2. Update sidebar in docs/.vitepress/config.ts
3. Cross-reference from related pages
4. Test locally with npm run docs:dev