Skip to main content

Module 32: Advanced Project Configuration

Master advanced TypeScript configuration for complex projects with multiple packages and build targets.

1. Project References​

// tsconfig.base.json
{
    "compilerOptions": {
        "composite": true,
        "declaration": true,
        "declarationMap": true,
        "incremental": true
    }
}

// packages/shared/tsconfig.json
{
    "extends": "../../tsconfig.base.json",
    "compilerOptions": {
        "outDir": "./dist",
        "rootDir": "./src"
    },
    "include": ["src/**/*"]
}

// packages/app/tsconfig.json
{
    "extends": "../../tsconfig.base.json",
    "compilerOptions": {
        "outDir": "./dist",
        "rootDir": "./src"
    },
    "include": ["src/**/*"],
    "references": [
        { "path": "../shared" }
    ]
}

Build with References​

tsc --build
tsc --build --watch
tsc --build --clean

2. Multiple Build Targets​

// tsconfig.esm.json (ES Modules)
{
    "extends": "./tsconfig.json",
    "compilerOptions": {
        "module": "ES2020",
        "outDir": "./dist/esm"
    }
}

// tsconfig.cjs.json (CommonJS)
{
    "extends": "./tsconfig.json",
    "compilerOptions": {
        "module": "CommonJS",
        "outDir": "./dist/cjs"
    }
}

// package.json
{
    "main": "./dist/cjs/index.js",
    "module": "./dist/esm/index.js",
    "types": "./dist/types/index.d.ts",
    "exports": {
        ".": {
            "import": "./dist/esm/index.js",
            "require": "./dist/cjs/index.js"
        }
    },
    "scripts": {
        "build": "npm run build:cjs && npm run build:esm",
        "build:cjs": "tsc -p tsconfig.cjs.json",
        "build:esm": "tsc -p tsconfig.esm.json"
    }
}

3. Path Mapping​

{
    "compilerOptions": {
        "baseUrl": ".",
        "paths": {
            "@app/*": ["src/*"],
            "@utils/*": ["src/utils/*"],
            "@models/*": ["src/models/*"],
            "@services/*": ["src/services/*"],
            "@components/*": ["src/components/*"]
        }
    }
}
// Use path aliases
import { formatDate } from "@utils/date";
import { User } from "@models/user";
import { UserService } from "@services/user";

4. Conditional Compilation​

// tsconfig.production.json
{
    "extends": "./tsconfig.json",
    "compilerOptions": {
        "removeComments": true,
        "sourceMap": false
    }
}

// tsconfig.development.json
{
    "extends": "./tsconfig.json",
    "compilerOptions": {
        "sourceMap": true,
        "inlineSourceMap": false
    }
}

5. Type-Only Imports/Exports​

// Efficient type imports
import type { User } from "./types";
import { api } from "./api";

// Type-only exports
export type { User, Post } from "./models";
export { createUser, getUser } from "./services";

6. Strict Mode Configuration​

{
    "compilerOptions": {
        // Enable all strict checks
        "strict": true,
        
        // Individual strict flags (if not using strict: true)
        "noImplicitAny": true,
        "strictNullChecks": true,
        "strictFunctionTypes": true,
        "strictBindCallApply": true,
        "strictPropertyInitialization": true,
        "noImplicitThis": true,
        "alwaysStrict": true,
        
        // Additional checks
        "noUnusedLocals": true,
        "noUnusedParameters": true,
        "noImplicitReturns": true,
        "noFallthroughCasesInSwitch": true,
        "noUncheckedIndexedAccess": true,
        "noPropertyAccessFromIndexSignature": true,
        "exactOptionalPropertyTypes": true
    }
}

7. Custom Type Directories​

{
    "compilerOptions": {
        "typeRoots": [
            "./node_modules/@types",
            "./types"
        ]
    }
}
project/
├── types/
│   ├── global.d.ts
│   ├── custom-library.d.ts
│   └── environment.d.ts

8. Incremental Builds​

{
    "compilerOptions": {
        "incremental": true,
        "tsBuildInfoFile": ".tsbuildinfo"
    }
}

9. Watch Mode Options​

{
    "watchOptions": {
        "watchFile": "useFsEvents",
        "watchDirectory": "useFsEvents",
        "fallbackPolling": "dynamicPriority",
        "synchronousWatchDirectory": true,
        "excludeDirectories": ["**/node_modules", "_build"],
        "excludeFiles": ["build/fileWhichChangesOften.ts"]
    }
}

10. Plugin Configuration​

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

11. Declaration Generation​

{
    "compilerOptions": {
        "declaration": true,
        "declarationMap": true,
        "emitDeclarationOnly": false,
        "declarationDir": "./types"
    }
}

12. Advanced Compiler Options​

{
    "compilerOptions": {
        // Module resolution
        "moduleResolution": "node",
        "resolveJsonModule": true,
        "allowSyntheticDefaultImports": true,
        "esModuleInterop": true,
        
        // Emit
        "outDir": "./dist",
        "rootDir": "./src",
        "removeComments": false,
        "importHelpers": true,
        "downlevelIteration": true,
        
        // Source maps
        "sourceMap": true,
        "inlineSourceMap": false,
        "inlineSources": false,
        
        // Experimental
        "experimentalDecorators": true,
        "emitDecoratorMetadata": true,
        
        // Advanced
        "skipLibCheck": true,
        "forceConsistentCasingInFileNames": true,
        "preserveConstEnums": false,
        "preserveSymlinks": false
    }
}

13. Monorepo Configuration​

// Root tsconfig.json
{
    "files": [],
    "references": [
        { "path": "./packages/shared" },
        { "path": "./packages/web" },
        { "path": "./packages/api" }
    ]
}

Key Takeaways​

✅ Project references for monorepos
✅ Path mapping for clean imports
✅ Multiple build targets for libraries
✅ Incremental builds for speed
✅ Strict mode for type safety
✅ Watch options for development

Practice Exercises​

Exercise 1: Configure Monorepo​

Set up project references for a multi-package repository.

Exercise 2: Dual Module Output​

Configure a library to output both CommonJS and ES modules.

Next Steps​

In Module 33, we'll explore Real-World Project Patterns with production-ready architectures.