Building Guide

Understanding the build process and output generation for the TypeScript Project Template.

Build Overview

The template uses TypeScript's compiler (tsc) for production builds, generating:

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

Build Commands

Basic Build

# Build for production
npm run build

Clean Build

# Remove previous build and rebuild
npm run clean
npm run build

Development Build

# Build and run immediately
npm run dev

Build Configuration

TypeScript Configurations

Development (tsconfig.json)

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

Production (tsconfig.build.json)

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

Build Output

Directory Structure

dist/
├── index.js           # Compiled main entry point
├── index.d.ts         # Type declarations
├── index.js.map       # Source map
├── utils.js           # Compiled utilities
├── utils.d.ts         # Utility type declarations
└── utils.js.map       # Utility source map

File Types

JavaScript Files (.js)

• Compiled TypeScript to JavaScript
• ES2022 target for modern Node.js
• ESNext modules for optimal tree-shaking

Declaration Files (.d.ts)

• Type information for TypeScript consumers
• API surface documentation
• IntelliSense support in IDEs

Source Maps (.js.map)

• Debug information linking JS to TS
• Stack trace mapping for errors
• Development debugging support

Build Process

Step-by-Step Process

1. Clean previous build (if using npm run clean)
2. Type checking across all source files
3. Compilation from TypeScript to JavaScript
4. Declaration generation for type information
5. Source map creation for debugging

Build Verification

# Verify build works
npm run build
npm start

# Check output structure
ls -la dist/

# Verify types are generated
ls -la dist/*.d.ts

Build Optimization

Compilation Speed

• Incremental compilation with TypeScript
• Project references for large codebases
• Parallel builds in CI/CD environments

Output Size

• Tree shaking with ES modules
• Dead code elimination with strict TypeScript
• Minimal runtime dependencies

Type Safety

• Strict TypeScript configuration
• No implicit any types
• Comprehensive type checking

Build Targets

Node.js Target

{
  "target": "ES2022",  // Modern Node.js features
  "module": "ESNext",  // Latest module syntax
  "lib": ["ES2022"]    // Standard library features
}

Browser Target (if needed)

{
  "target": "ES2020",     // Broader browser support
  "module": "ES2020",     // Module compatibility
  "lib": ["ES2020", "DOM"] // Include DOM types
}

Build Scripts

Package.json Scripts

{
  "scripts": {
    "build": "tsc -p tsconfig.build.json",
    "clean": "rm -rf dist/",
    "dev": "npm run build && npm start",
    "start": "node dist/index.js"
  }
}

Custom Build Scripts

#!/bin/bash
# build.sh - Custom build script

echo "🧹 Cleaning previous build..."
npm run clean

echo "🔍 Type checking..."
npx tsc --noEmit

echo "🏗️ Building..."
npm run build

echo "✅ Build complete!"
ls -la dist/

Build Validation

Post-Build Checks

# Verify JavaScript syntax
node -c dist/index.js

# Check for TypeScript errors
npx tsc --noEmit

# Validate package structure
npm pack --dry-run

Runtime Testing

# Test built output
npm run build
npm start

# Verify all exports work
node -e "console.log(require('./dist/index.js'))"

CI/CD Integration

GitHub Actions Build

- name: Build project
  run: npm run build

- name: Verify build output
  run: |
    test -f dist/index.js
    test -f dist/index.d.ts
    test -f dist/utils.js
    test -f dist/utils.d.ts

Build Artifacts

• Store build output for deployment
• Cache dependencies for faster builds
• Parallel builds across Node.js versions

Troubleshooting

Common Build Issues

TypeScript Errors

# Check for type errors
npx tsc --noEmit

# Verbose type checking
npx tsc --noEmit --listFiles

Module Resolution

# Debug module resolution
npx tsc --traceResolution

# Check module paths
npx tsc --showConfig

Build Performance

# Analyze build performance
npx tsc --diagnostics

# Enable incremental builds
npx tsc --incremental

Build Environment Issues

Node.js Version

# Check Node.js version
node --version

# Use specific Node.js version
nvm use 20

Dependency Issues

# Clean install dependencies
rm -rf node_modules package-lock.json
npm install

Advanced Build Configuration

Custom TypeScript Paths

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

Build Plugins

{
  "compilerOptions": {
    "plugins": [
      {
        "name": "typescript-plugin-css-modules"
      }
    ]
  }
}

Multiple Build Targets

# Build for different environments
npm run build:node    # Node.js target
npm run build:browser # Browser target
npm run build:all     # All targets

Distribution

NPM Package Preparation

{
  "main": "dist/index.js",
  "types": "dist/index.d.ts",
  "files": [
    "dist/**/*",
    "README.md",
    "LICENSE"
  ]
}

Build for Publishing

# Prepare for NPM publishing
npm run build
npm pack
npm publish --dry-run

Next Steps

• Quality Gates - Ensure build quality
• Deployment - Deploy built artifacts
• Configuration - Advanced TypeScript setup