How to fix Compiler option 'X' is not valid in TypeScript

### TypeScript Version-Specific Options

TypeScript regularly introduces new compiler options. Here's a timeline of notable additions:

TypeScript 5.0 (March 2023):
- verbatimModuleSyntax - Stricter import/export syntax checking
- ignoreDeprecations - Suppress deprecation warnings
- moduleResolution: "bundler" - Optimized for modern bundlers

TypeScript 4.7 (May 2022):
- moduleSuffixes - Platform-specific module resolution (.ios.ts, .native.ts)
- customConditions - Custom package.json export conditions

TypeScript 4.5 (November 2021):
- preserveValueImports - Keep imports that might be used at runtime

When copying configuration from online examples, always check which TypeScript version the example uses. A tsconfig from a TypeScript 5.0+ tutorial won't work with TypeScript 4.x.

### Deprecated and Removed Options

TypeScript occasionally deprecates options. Using these will cause errors in newer versions:

Removed in TypeScript 5.0:
- importsNotUsedAsValues → use verbatimModuleSyntax
- preserveValueImports → use verbatimModuleSyntax

If you're upgrading TypeScript and encounter errors about invalid options, check the [TypeScript Breaking Changes](https://github.com/microsoft/TypeScript/wiki/Breaking-Changes) documentation.

### Tool-Specific Limitations

ts-node doesn't support:
- moduleSuffixes (as of ts-node 10.9)
- Some experimental options

Solution: Use tsx (a faster, more compatible alternative to ts-node):

npm install -D tsx

# Run files with tsx instead of ts-node
npx tsx src/index.ts

SWC (speedy-web-compiler) doesn't use all TypeScript compiler options since it doesn't do type checking. It ignores options like:
- strict
- noUnusedLocals
- Most type-checking flags

When using SWC, you still need to run tsc --noEmit separately for type checking.

### Validating tsconfig.json Schema

Modern IDEs provide schema validation for tsconfig.json. Ensure your editor is using the correct JSON schema:

VS Code automatically uses the TypeScript schema. If validation isn't working:

1. Check your VS Code settings include TypeScript
2. Install the TypeScript extension (usually bundled)
3. Verify the schema is associated with tsconfig.json files

You can also validate manually:

# Generate merged config to see what TypeScript actually uses
npx tsc --showConfig

# This shows the final configuration after extends, defaults, etc.

### Extends and Option Inheritance

When using extends, child configs can override parent options, but can't use options the parent doesn't recognize:

// tsconfig.base.json (TypeScript 4.9)
{
  "compilerOptions": {
    "target": "ES2022"
  }
}

// tsconfig.json (TypeScript 5.0)
{
  "extends": "./tsconfig.base.json",
  "compilerOptions": {
    "verbatimModuleSyntax": true  // ✓ OK, added in child
  }
}

But if the base config has an invalid option, extending it will fail:

// tsconfig.base.json
{
  "compilerOptions": {
    "unknownOption": true  // ✗ Invalid
  }
}

// tsconfig.json
{
  "extends": "./tsconfig.base.json"  // ✗ Fails due to parent's invalid option
}

### Debugging Configuration Issues

Use these commands to debug tsconfig problems:

# Show final merged configuration
npx tsc --showConfig

# Show all available compiler options
npx tsc --all

# Show TypeScript help with valid options
npx tsc --help

# List files that will be compiled
npx tsc --listFiles | head -20

For complex configurations with multiple extends and overrides, --showConfig is invaluable for understanding what TypeScript actually sees.