WebsiteLogo

Basic TypeScript Compiler Options

Understand the core options for the TypeScript compiler (tsconfig.json) and how to configure them for your project.

⬅ Previous Next ➡

TypeScript Include/Exclude: A Beginner's Guide

This guide explains how to use the include and exclude options in your tsconfig.json file to control which files are included in your TypeScript compilation.

TypeScript uses the tsconfig.json file to manage project settings, including which files should be compiled into JavaScript. The include and exclude properties provide a powerful way to selectively include or exclude files from the compilation process.

Understanding tsconfig.json

The tsconfig.json file is a configuration file that TypeScript uses to understand how to compile your project. It specifies compiler options, such as the target JavaScript version, module system, and source maps, as well as the files to include in the compilation.

Basic tsconfig.json Example

 {
  "compilerOptions": {
    "target": "es5",
    "module": "commonjs",
    "sourceMap": true,
    "outDir": "./dist"
  }
}

This basic tsconfig.json file defines some common compiler options. It compiles TypeScript code to ES5, uses CommonJS modules, generates source maps, and outputs the compiled JavaScript files to the ./dist directory.

Using include

The include option specifies an array of glob patterns that match the files you want to include in your compilation. If `include` is specified with `exclude`, only the files in `include` that *aren't* in `exclude` are compiled.

A glob pattern is a string that uses wildcards to match file names. Common wildcards include:

  • *: Matches any number of characters (except directory separators).
  • ?: Matches a single character.
  • **: Matches any number of directories and subdirectories. This is particularly useful for including files deeply nested within your project structure.

Example include configurations:

 // Include all .ts files in the src directory
{
  "compilerOptions": {
    "target": "es5",
    "module": "commonjs",
    "sourceMap": true,
    "outDir": "./dist"
  },
  "include": ["src/**/*"]
}

This configuration includes all .ts files within the src directory and its subdirectories. The **/* pattern matches any directory structure and any file within those directories.

 // Include specific files
{
  "compilerOptions": {
    "target": "es5",
    "module": "commonjs",
    "sourceMap": true,
    "outDir": "./dist"
  },
  "include": ["src/main.ts", "src/utils.ts"]
}

This configuration explicitly includes only src/main.ts and src/utils.ts. Other TypeScript files in your project will *not* be compiled.

Using exclude

The exclude option specifies an array of glob patterns that match the files you want to *exclude* from your compilation. This is useful when you want to include most files in a directory but exclude specific ones, like test files, configuration files, or temporary files.

Example exclude configurations:

 // Exclude all test files
{
  "compilerOptions": {
    "target": "es5",
    "module": "commonjs",
    "sourceMap": true,
    "outDir": "./dist"
  },
  "include": ["src/**/*"],
  "exclude": ["src/**/*.spec.ts", "src/**/*.test.ts"]
}

This configuration includes all .ts files in the src directory, but excludes any files ending in .spec.ts or .test.ts (typically used for unit tests).

 // Exclude entire directories
{
  "compilerOptions": {
    "target": "es5",
    "module": "commonjs",
    "sourceMap": true,
    "outDir": "./dist"
  },
  "include": ["src/**/*"],
  "exclude": ["src/tests"]
}

This configuration includes all .ts files in the src directory, but excludes the entire src/tests directory and its contents.

Combining include and exclude

You can use both include and exclude together for fine-grained control over the compilation process. When used together, the TypeScript compiler first includes all files matching the include patterns and then excludes any files matching the exclude patterns.

Example combining include and exclude

 {
  "compilerOptions": {
    "target": "es5",
    "module": "commonjs",
    "sourceMap": true,
    "outDir": "./dist"
  },
  "include": ["src/**/*"],
  "exclude": ["src/tests/**/*", "src/temp.ts"]
}

This configuration includes all .ts files in the src directory *except* for those in the src/tests directory and the specific file src/temp.ts.

Common Mistakes and Best Practices

  • Forgetting to use ** for recursive directory matching: Use src/**/* to include files in all subdirectories, not just the top-level src directory.
  • Incorrect glob patterns: Double-check your glob patterns to ensure they accurately match the files you intend to include or exclude. Use online glob testing tools to verify your patterns.
  • Overly broad exclude patterns: Be specific with your exclude patterns to avoid accidentally excluding important files.
  • Not specifying include or files: If neither `include` nor `files` are specified, the compiler defaults to including all .ts files in the directory containing the tsconfig.json file, and all its subdirectories. This can lead to unexpected compilation results. Best practice is to always be explicit.
  • Using relative paths: The paths in include and exclude are resolved relative to the location of the tsconfig.json file.

Conclusion

The include and exclude options in tsconfig.json are essential tools for managing TypeScript projects of any size. By understanding how to use glob patterns, you can precisely control which files are compiled, ensuring a clean and efficient development workflow.

⬅ Previous Next ➡