tsconfig setting in Angular

한국어(Korean) Page

When you bootstrap a new Angular project with ng new, the CLI automatically generates several configuration files. Among them, tsconfig.json is one that many developers leave untouched, often overlooking its power. But this file is the “brain” of the TypeScript compiler, and understanding it is key to building robust, modern Angular applications.

As of Angular 18, correctly configuring your tsconfig.json can significantly improve code stability, enable the latest JavaScript features, and even boost your development productivity. Today, we’ll dive deep into how tsconfig.json works within an Angular project and explore which keys you can tweak to maximize your project’s potential.

---

1. The Three Musketeers of tsconfig.json in Angular: A Clear Separation of Concerns

If you look inside the root folder of a project generated by the Angular CLI, you’ll find multiple tsconfig.json files. This structure is designed to separate configurations for different purposes, using inheritance to avoid duplication.

• tsconfig.json (Root)
  • This is the base TypeScript configuration for the entire workspace.
  • Settings defined here are inherited by all other tsconfig files in the project.
  • It’s the perfect place for rules that should apply universally to your application, libraries, and tests.
• tsconfig.app.json
  • This configuration file is used specifically for building your application.
  • It extends the root tsconfig.json and can override or add settings tailored for the application bundle.
  • It uses files or include properties to specify the exact scope of source files to be compiled.
• tsconfig.spec.json
  • This file is used when running unit tests (e.g., with Karma/Jasmine).
  • Like its app counterpart, it extends the base configuration and adds settings specific to the testing environment, such as including type definitions for jasmine.

This layered structure allows for clean and maintainable configurations, separating the concerns of building, testing, and general development.

---

2. Demystifying Key compilerOptions from an Angular Perspective

The most critical section of tsconfig.json is the compilerOptions object. The key-value pairs here dictate how your TypeScript code is transpiled into JavaScript. Let’s break down the options that have the most significant impact on an Angular project.

Key	Role & Impact on Angular	Recommended Value (Angular 18)
target	Specifies the ECMAScript version of the output JavaScript. Since Angular targets modern browsers, we can use a recent version.	“ES2022”
module	Defines the module system. To use modern features like dynamic import(), ESNext or ES2022 is recommended.	“ES2022”
lib	Lists the built-in type definition files to include during compilation. For a browser-based app, DOM is essential.	[“ES2022”, “DOM”]
strict	One of the most important options. Setting this to true enables a suite of strict type-checking rules like strictNullChecks and noImplicitAny. This drastically improves code reliability and is a must-have for any serious project.	true
forceConsistentCasingInFileNames	When true, it enforces strict case-sensitivity for file names. This prevents potential bugs when collaborating across different operating systems (e.g., Windows vs. macOS/Linux).	true
experimentalDecorators	Absolutely essential for Angular. This enables the use of decorators like @Component and @Injectable, which are the cornerstone of the framework. Without it, your Angular app won’t work.	true
emitDecoratorMetadata	Emits type metadata for decorated classes and properties. This metadata is crucial for Angular’s Dependency Injection (DI) system to resolve types and inject dependencies correctly at runtime.	true
paths	Creates module path aliases to simplify imports. It transforms messy relative paths (../../../) into clean, absolute-like paths. (See example below)	(User-defined)

---

3. Level Up Your Project: Practical tsconfig.json Recipes

Enough theory! Let’s see how tweaking these settings can solve real-world problems and improve your Angular project.

Example 1: Catching Runtime Errors at Compile Time with strict Mode

This is arguably the most powerful feature TypeScript offers. Here’s a clear example of why strict: true is non-negotiable.

• The Problem: A component needs to display user information, but the currentUser can be null if no one is logged in.

// user.service.ts
@Injectable({ providedIn: 'root' })
export class UserService {
  // The user might not exist (can be null)
  currentUser: { name: string; email: string } | null = null;
}

// profile.component.ts
@Component({ ... })
export class ProfileComponent {
  constructor(private userService: UserService) {}

  // With strict: false, this code compiles without any errors.
  // However, it will crash at runtime with a "Cannot read properties of null (reading 'name')" error if currentUser is null!
  welcomeMessage = `Welcome, ${this.userService.currentUser.name}!`;
}

• The Solution (strict: true):

  With strict: true enabled in tsconfig.app.json, the TypeScript compiler is smart enough to know that this.userService.currentUser could be null and immediately flags it as a compile-time error.

  Compile Error: Object is possibly ‘null’.

  This error forces the developer to handle the null case gracefully, preventing the runtime crash entirely.

// profile.component.ts (The Fix)
export class ProfileComponent {
  welcomeMessage: string;

  constructor(private userService: UserService) {
    // Safely handle the null case using optional chaining and the nullish coalescing operator
    const userName = this.userService.currentUser?.name ?? 'Guest';
    this.welcomeMessage = `Welcome, ${userName}!`;
  }
}

Example 2: Cleaning Up Messy Imports with paths Aliases

As your project grows, you’ll inevitably face “relative path hell.”

• The Problem:

// src/app/features/orders/components/order-details/order-details.component.ts
import { AuthService } from '../../../../core/services/auth.service';
import { Product } from '../../../../shared/models/product.model';

• The Solution (using paths):

  In your root tsconfig.json, add baseUrl and paths to the compilerOptions.

// tsconfig.json
{
  "compilerOptions": {
    "baseUrl": "./", // baseUrl is required to use paths
    "paths": {
      "@core/*": ["src/app/core/*"],
      "@shared/*": ["src/app/shared/*"],
      "@features/*": ["src/app/features/*"]
    }
  }
}

• The Improved Code:

  Now, you can import modules from anywhere in your project using clean, absolute-like paths. This makes your code more readable and makes refactoring (moving files) much less painful.

// src/app/features/orders/components/order-details/order-details.component.ts
import { AuthService } from '@core/services/auth.service';
import { Product } from '@shared/models/product.model';

Example 3: Enforcing Code Quality with noUnusedLocals

Unused variables and imports are code smells that clutter your codebase and can hide potential bugs.

• The Solution (enabling noUnusedLocals):

  By adding this option to tsconfig.app.json, the compiler will throw an error if it finds any declared local variables or private members that are never used, forcing you to maintain a cleaner codebase.

// tsconfig.app.json
{
  "compilerOptions": {
    "noUnusedLocals": true,
    "noUnusedParameters": true // Also catches unused function parameters
  }
}

---

Conclusion

Your tsconfig.json is not just a configuration file; it’s a powerful safety net that guards the quality and stability of your entire project. In a modern framework like Angular 18, which is built on the foundation of TypeScript’s strong type system, mastering these compiler options is more critical than ever.

Take a moment to open your tsconfig.json file today. Ensure strict mode is enabled, set up some path aliases, and enforce cleaner code with noUnusedLocals. These small changes will yield massive returns in your development experience and the long-term health of your application.