Skip to content
Tutorials Center
My learning

Topics

TypeScript Reference ยท tsconfig: Type Checking Options

TypeScript forceConsistentCasingInFileNames option

Reference for forceConsistentCasingInFileNames: why file name casing breaks builds between Windows, macOS and Linux, and how the option catches it early.

forceConsistentCasingInFileNames makes the compiler report an error when the same file is referred to with different letter casing, for example import "./Utils" in one place and import "./utils" in another. Windows and default macOS volumes ignore case, so both imports work on a developer machine. Linux servers and most CI systems are case sensitive, so the build that passed locally fails there, or worse, loads two copies of one module.

Current releases enable it by default. You normally only meet it as an error, or as an old false in a config that should be removed.

JSON
{
  "compilerOptions": {
    "forceConsistentCasingInFileNames": true
  }
}

Try it

The compiler checks file paths, which a single file cannot show. These examples demonstrate the underlying problem: paths that differ only in case are different strings, but one file on a case-insensitive disk.

TypeScript Two spellings, one file

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or readFileSync(0)), it gets the next line from this box.

TypeScript A tiny casing checker

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or readFileSync(0)), it gets the next line from this box.

Syntax

JSON
{ "compilerOptions": { "forceConsistentCasingInFileNames": true } }
Part Description
Type boolean. Default: true in current releases (older versions defaulted to false).
Command line tsc --forceConsistentCasingInFileNames
Error Reports that the file name differs from an already included file only in casing (TS1149 for a file name, TS1261 for an already included file).

Usage notes

  • It checks import/export specifiers, /// <reference> directives, include globs that resolve to files, and the files already in the program.
  • The error names both spellings, so the fix is to pick one and rename every use. If the file on disk has the wrong case, rename it with Git (git mv), because Git on case-insensitive systems may not notice a case-only rename otherwise.
  • Without the check, a Windows build can end up with two copies of one module (Utils.ts and utils.ts), which breaks instanceof checks and singletons.
  • Do not rely on case-insensitivity as a feature. Bundlers and Node on Linux resolve exact names only.
  • The editor may keep a stale module list after a rename; restart the TypeScript server if the error persists.