TypeScript throwing “Cannot find module” errors when you’re using path aliases can make you want to pull your hair out. This error means TypeScript can’t resolve your custom import paths like `@components/Button` or `@utils/helpers`, even though your code might run perfectly fine.
Step-by-Step Fixes
Step 1: Double-check your tsconfig.json paths
Open your `tsconfig.json` file and look for the `compilerOptions` section. You need both `baseUrl` and `paths` configured correctly:
“`json
{
“compilerOptions”: {
“baseUrl”: “./”,
“paths”: {
“@components/“: [“src/components/“],
“@utils/“: [“src/utils/“],
“@/“: [“src/“]
}
}
}
“`
Make sure your `baseUrl` points to the right directory. Most projects use `”./”` for the project root or `”./src”` if everything lives in a src folder. The paths should match your actual folder structure exactly.
Step 2: Restart your TypeScript server
Your IDE might be holding onto old configuration. In VS Code, press `Ctrl+Shift+P` (or `Cmd+Shift+P` on Mac) and type “TypeScript: Restart TS Server”. In WebStorm, go to File → Invalidate Caches and Restart. This forces your editor to reload the TypeScript configuration.
Step 3: Check your module resolution settings
Add or verify these settings in your `tsconfig.json`:
“`json
{
“compilerOptions”: {
“moduleResolution”: “node”,
“resolveJsonModule”: true,
“esModuleInterop”: true,
“allowSyntheticDefaultImports”: true
}
}
“`
The `moduleResolution: “node”` setting is crucial for path aliases to work properly in most Node.js and bundler environments.
Step 4: Install and configure a runtime resolver
TypeScript only handles type checking, not actual module resolution at runtime. For Node.js projects, install `tsconfig-paths`:
“`bash
npm install –save-dev tsconfig-paths
“`
Then update your scripts in `package.json`:
“`json
{
“scripts”: {
“dev”: “ts-node -r tsconfig-paths/register src/index.ts”,
“build”: “tsc && tsc-alias”
}
}
“`
For webpack projects, add this to your webpack config:
“`javascript
module.exports = {
resolve: {
alias: {
‘@components’: path.resolve(__dirname, ‘src/components’),
‘@utils’: path.resolve(__dirname, ‘src/utils’)
}
}
};
“`
Step 5: Verify your build tool configuration
Different build tools need different configurations. For Vite projects in 2025, install `vite-tsconfig-paths`:
“`bash
npm install –save-dev vite-tsconfig-paths
“`
Then add it to your `vite.config.ts`:
“`typescript
import { defineConfig } from ‘vite’;
import tsconfigPaths from ‘vite-tsconfig-paths’;
export default defineConfig({
plugins: [tsconfigPaths()]
});
“`
For Next.js projects, path aliases should work out of the box if your `tsconfig.json` is configured correctly.
Step 6: Clean and rebuild everything
Sometimes cached files cause issues. Run these commands in order:
“`bash
rm -rf node_modules
rm -rf dist
rm -rf .next
npm install
npm run build
“`
This nuclear option often fixes stubborn path resolution problems.
Likely Causes
Cause #1: Mismatched paths between TypeScript and your bundler
Your TypeScript config might say one thing while your webpack, Vite, or other bundler expects something else. This commonly happens when you configure path aliases in `tsconfig.json` but forget to mirror them in your bundler configuration.
To check: Compare your `tsconfig.json` paths with your bundler config. They should match exactly. Look for typos or different path structures.
What to do: Make sure every alias in your TypeScript config has a matching alias in your bundler. Keep the naming consistent across all configurations.
Cause #2: Wrong baseUrl setting
The `baseUrl` acts as the starting point for all your path aliases. If it’s pointing to the wrong directory, none of your aliases will resolve correctly.
To check: Look at where your `tsconfig.json` file sits relative to your source files. If `tsconfig.json` is in your project root and your code is in a `src` folder, your baseUrl should probably be `”./”` or `”./src”`.
What to do: Test different baseUrl values. Start with `”./”` and adjust based on your project structure. Remember that paths are resolved relative to the baseUrl.
Cause #3: IDE cache or outdated TypeScript version
Your IDE might be using cached TypeScript settings or an older TypeScript version that doesn’t fully support path mapping.
To check: Run `npx tsc –version` to see your TypeScript version. Anything below 4.0 might have path alias issues. Check your IDE’s TypeScript version in its settings.
What to do: Update TypeScript to the latest version with `npm install –save-dev typescript@latest`. Clear your IDE cache and restart it completely.
When to Call Expert Help
You should consider getting professional help when you’ve tried all these steps and still see errors, especially if your project has a complex build setup with multiple tools like monorepos, custom webpack configurations, or enterprise build systems.
Red flags that indicate you need expert assistance include path aliases working in development but failing in production builds, errors only appearing in CI/CD pipelines, or when your project uses uncommon bundlers or build tools not covered here.
A TypeScript expert can audit your entire build configuration, identify conflicts between different tools, and set up a robust path resolution system that works across all environments.
Copy-Paste Prompt for AI Help
If you need more specific help, copy this prompt and paste it into ChatGPT or Claude:
“I’m getting ‘Cannot find module’ errors in TypeScript when using path aliases. My project uses [YOUR BUILD TOOL: webpack/Vite/Next.js/etc] and TypeScript version [YOUR VERSION]. Here’s my current tsconfig.json paths configuration: [PASTE YOUR PATHS CONFIG]. The error happens when I import [PASTE EXAMPLE IMPORT]. My file structure looks like [DESCRIBE YOUR FOLDER STRUCTURE]. What specific configuration changes do I need to make this work?”
Remember to replace the bracketed sections with your actual project details for the most accurate help.