How to fix 'forceConsistentCasingInFileNames' is not set, but 'paths' config is used in TypeScript

### Why Path Mapping Requires Consistent Casing

Path mapping creates virtual module resolution that can bypass normal file system checks. When TypeScript resolves an import like @components/Button:

1. It maps @components/* to src/components/* based on your paths config
2. It attempts to find the file at that location
3. On Windows/macOS, the file system returns the file even if casing is wrong
4. On Linux, incorrect casing fails at runtime (but TypeScript already compiled it)

The forceConsistentCasingInFileNames option makes TypeScript verify casing during step 2, catching the issue before deployment.

### Known Issues with Paths and Casing

There are several documented TypeScript issues related to this interaction:

Configuration inheritance problems:
When using extends in tsconfig.json, the baseUrl can get resolved with unexpected casing, particularly on case-insensitive file systems. This manifests as errors like:

File name 'C:/Project/src/...' differs from already included file name
'c:/Project/src/...' only in casing

Workaround: Set baseUrl explicitly in the extending configuration file, not just in the base config.

Node16/NodeNext module resolution:
When using moduleResolution: "node16" or "nodenext", type reference directives can break on macOS if there are capital letters in the project path. This is a known limitation tracked in TypeScript issue #50544.

### Best Practice tsconfig.json for Cross-Platform Projects

{
  "compilerOptions": {
    // Module resolution
    "moduleResolution": "bundler",  // or "node16" for Node.js
    "baseUrl": "./src",
    "paths": {
      "@/*": ["./*"]
    },

    // Strict type checking
    "strict": true,
    "noImplicitAny": true,
    "strictNullChecks": true,

    // Cross-platform compatibility
    "forceConsistentCasingInFileNames": true,
    "esModuleInterop": true,
    "skipLibCheck": true,

    // Output
    "target": "ES2020",
    "module": "ESNext",
    "lib": ["ES2020", "DOM"]
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}

### ESLint Rule for Import Casing

You can enforce correct casing at the linting level with eslint-plugin-import:

npm install -D eslint-plugin-import

// .eslintrc.json
{
  "plugins": ["import"],
  "rules": {
    "import/no-unresolved": "error"
  },
  "settings": {
    "import/resolver": {
      "typescript": {
        "alwaysTryTypes": true
      }
    }
  }
}

This catches import casing issues even before TypeScript compilation.

### Debugging Casing Issues

If you're still experiencing casing-related errors after enabling the option:

1. Check actual file system casing:

# On Unix-like systems
find src -name "*.ts" -o -name "*.tsx"

# Look for duplicates that differ only in casing
find src -type f | sort -f | uniq -i -d

2. Use TypeScript's trace resolution:

npx tsc --traceResolution > resolution.log
grep -i "casing" resolution.log

3. Check Git configuration:
Sometimes Git on Windows checks out files with incorrect casing. Configure Git to preserve casing:

git config core.ignorecase false

### Migration Strategy for Large Codebases

If you have an existing large codebase with many casing issues:

1. Enable the option but temporarily set it to false
2. Gradually fix files in batches
3. Use a script to find all casing mismatches:

// find-casing-issues.js
const { execSync } = require('child_process');
const output = execSync('npx tsc --noEmit 2>&1', { encoding: 'utf-8' });
const casingErrors = output.match(/differs.*only in casing/g);
console.log(`Found ${casingErrors?.length || 0} casing issues`);

4. Once all issues are fixed, enable forceConsistentCasingInFileNames: true permanently