Project Structure & tsconfig

Why project structure matters

TypeScript is not just about types. In real-world applications, project structure and compiler configuration determine maintainability, performance, and team productivity. A clean folder structure combined with a properly configured tsconfig.json file prevents architectural chaos as the project grows.

Basic folder structure

A common production-ready structure looks like this:

project-root/
├── src/
│   ├── domain/
│   ├── services/
│   ├── controllers/
│   ├── utils/
│   └── index.ts
├── dist/
├── package.json
├── tsconfig.json

The src directory contains TypeScript source code. The dist directory contains compiled JavaScript output.

Understanding tsconfig.json

The tsconfig.json file controls how TypeScript compiles your project. It defines strictness rules, module resolution, output paths, and more.

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "CommonJS",
    "rootDir": "./src",
    "outDir": "./dist",
    "strict": true,
    "esModuleInterop": true,
    "forceConsistentCasingInFileNames": true,
    "skipLibCheck": true
  }
}

Strict mode is mandatory

The "strict": true setting enables all strict type-checking options. In production projects, strict mode should never be disabled. It prevents null-related bugs, unsafe assignments, and implicit any types.

rootDir and outDir

rootDir defines where your TypeScript source files live. outDir defines where compiled JavaScript is emitted. Keeping these separate prevents mixing source and output files.

Module system choices

Depending on your environment (Node.js, bundlers, or modern ESM), you may use CommonJS or ESNext modules. Choose a module system consistent with your runtime.

Path aliases

Large projects benefit from path aliases to avoid long relative imports.

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

This improves readability and refactor safety.

Incremental builds

For larger projects, enable incremental compilation to speed up builds.

{
  "compilerOptions": {
    "incremental": true
  }
}

Common mistakes

• Disabling strict mode to silence errors.
• Mixing compiled JavaScript inside src.
• Using inconsistent module systems.
• Ignoring compiler warnings in CI pipelines.

Production guidance

• Always enable strict mode.
• Separate source and build output directories.
• Use path aliases in medium to large projects.
• Keep tsconfig.json under version control and review changes carefully.

What’s next

Now that your project is structured correctly, the next step is integrating TypeScript with Node.js for backend applications.