Debug: TypeScript 'cannot find module' for local imports

TypeScript reports 'Cannot find module' for local file imports even though the file exists.

Common causes and fixes:

1. Missing file extension in import:

// Bad: import { foo } from './utils' (might need extension)
// With moduleResolution: 'nodenext', extension is required:
import { foo } from './utils.js' // Yes, .js even for .ts files!

1. Path aliases not configured:

// tsconfig.json:
{
"compilerOptions": {
"baseUrl": ".",
"paths": {
"@/": ["src/"],
"@utils/": ["src/utils/"]
}
}
}
// Also configure in bundler (webpack/vite/etc.)

1. File not in tsconfig include:

{
"include": ["src/**/*"], // File must be within this
"exclude": ["node_modules"]
}

1. Missing type declarations for non-TS files:

// src/types/assets.d.ts
declare module '*.svg' {
const content: string;
export default content;
}
declare module '*.css' {
const classes: Record<string, string>;
export default classes;
}

1. Monorepo/workspace issues:

// Ensure project references in tsconfig:
{ "references": [{ "path": "../shared" }] }

1. Restart TS server:

// VSCode: Cmd+Shift+P > TypeScript: Restart TS Server