tsconfig.json vs tsconfig-app.json vs tsconfig.spec.json

In many TypeScript projects, especially those generated by the Angular CLI, you will see multiple tsconfig.*.json files. This hierarchy allows for specialized configurations while inheriting a common base to prevent redundant and conflicting settings.

Here is a breakdown of the roles for tsconfig.json, tsconfig.app.json, and tsconfig.spec.json.

tsconfig.json

The root tsconfig.json file serves as the base configuration for the entire project. In a modern Angular application, this file typically acts as a "solution-style" configuration for tools and IDEs, which may use it to understand the overall structure of the project. A more specific file, like tsconfig.base.json, holds the shared compiler options that other configurations will extend.

Key purpose

• Editor support: Provides IDEs with a project-wide context for features like autocompletion and linting.
• Centralized settings: Contains the core compiler settings that are consistent across the entire project, such as the TypeScript version target and strictness rules.

tsconfig.app.json

The tsconfig.app.json file is responsible for building the actual application code. It extends the main or base configuration but provides specific settings tailored for compiling the application's source files.

Key purpose

• Application build: Specifies the configuration used by the Angular CLI when you run ng build or ng serve.
• Narrowed scope: Overrides or adds settings for the application's code. For example, it defines the include and exclude paths to compile only the application's source files and might change the types array to include only the necessary type definitions for the browser environment.
• Multi-project support: In a monorepo, each application might have its own tsconfig.app.json to define its individual build settings, allowing them to vary from the global workspace configuration.

tsconfig.spec.json

The tsconfig.spec.json file is specifically for compiling the project's test files. Like the application config, it extends the base tsconfig.json but is optimized for the testing environment.

Key purpose

• Testing configuration: Used by the test runner (like Karma/Jasmine) when you execute ng test.
• Test-specific options: Includes the necessary type definitions for testing frameworks, such as Jasmine. The types array is typically set to ["jasmine"] to ensure the correct global types are available for your test files.
• Different module system: The module setting might be different from the main application to better suit the Node.js test runner environment.
• Isolated compilation: Explicitly includes the test (or "spec") files and typically excludes the main application files, ensuring the test and application code are compiled with their distinct sets of rules.

Inheritance example

In a typical Angular project, the inheritance structure looks like this:

tsconfig.app.json extends tsconfig.base.json
tsconfig.spec.json extends tsconfig.base.json

The base file contains the common settings, and the other files provide overrides for their specific contexts. Here is a simplified example of how they interact:

tsconfig.json or tsconfig.base.json – The Foundation

• Located at the root of the Angular workspace.
• Defines base compiler options like target, module, lib, and strictness flags.
• Used as a shared base for other configs via extends.

    {
    "compilerOptions": {
    "target": "ES2022",
    "module": "ES2022",
    "strict": true,
    "moduleResolution": "node",
    "lib": ["ES2022", "dom"]
      }
    }              

tsconfig.app.json – For Application Code

• Extends tsconfig.json.
• Focuses on compiling files in src/ (excluding tests).
• Often includes "exclude": ["**/*.spec.ts"] to skip test files.

    {
    "extends": "./tsconfig.base.json",
    "compilerOptions": {
    "outDir": "./dist/out-tsc",
    "types": []
    },
    "files": [],
    "include": ["src/**/*.ts"],
    "exclude": ["src/**/*.spec.ts"]
    }

tsconfig.spec.json – For Test Code

• Also extends tsconfig.json.
• Includes test-related typings like Jasmine or Jest.
• Used by Angular CLI during ng test.

{
  "extends": "./tsconfig.base.json",
  "compilerOptions": {
    "module": "commonjs",
    "types": ["jasmine"]
  },
  "include": [
    "src/**/*.spec.ts"
  ]
}

🧩 Overview of TypeScript Config Files in Angular

File Name	Purpose	Inherits From	Typical Use Case
tsconfig.json	Global base configuration for TypeScript compiler	—	Shared settings across all subprojects
tsconfig.app.json	Configuration specific to the Angular application code (src/)	tsconfig.json	App compilation, excluding tests and tooling
tsconfig.spec.json	Configuration for unit tests (usually using Jasmine/Karma)	tsconfig.json	Test compilation with additional type definitions