A path alias works in the editor but not in the webpack build
Module not foundShort answer
TypeScript paths only describe aliases to the compiler; webpack must be told too. Since webpack 5.105 set resolve.tsconfig to read compilerOptions.paths. On older versions or with custom setups write resolve.alias with absolute paths. An alias that points at a file also blocks sub-paths.
Fix it fast
1Find out which cause you have
Compare the alias in tsconfig.json with what webpack was given. Whatever is missing from webpack.config is the problem.
grep -n -A6 "paths" tsconfig.json grep -n -A8 "alias\|tsconfig" webpack.config.*2Match what you see, then jump to its fix
- 1
tsc and the editor accept the import, but the bundler cannot resolve it.webpack was never told about compilerOptions.pathsFix - 2
npx webpack --version prints a version below 5.105, or the option is rejected as unknown.An older webpack, so the alias must be written in webpack itselfFix - 3
import 'xyz' works but import 'xyz/file.js' does not.The alias points at a file, so sub-paths failFix - 4
tsconfig: true is set, yet paths from tsconfig.app.json are ignored.The wrong tsconfig file is read in a multi-config or monorepo projectFix
- 1
What does the error look like?
Module not foundCan't resolve
Cause 1 of 4
webpack was never told about compilerOptions.paths
1Check
The guide says resolve.tsconfig reads baseUrl and paths from tsconfig.json from webpack 5.105 on, and that it only handles resolution, not transpiling.
npx webpack --version2Fix
Turn on resolve.tsconfig. Keep your ts-loader or Babel rule; it is still needed.
// tsconfig.json
{ "compilerOptions": { "baseUrl": ".", "paths": { "@/*": ["src/*"] } } }
// webpack.config.js
resolve: { tsconfig: true },3Verify
import Button from '@/components/Button' resolves in the build.
npx webpack --mode developmentConfirmed by webpack.js.org
Cause 2 of 4
An older webpack, so the alias must be written in webpack itself
1Check
resolve.tsconfig is documented as available from 5.105.0. Before that, mirror each path in resolve.alias.
npx webpack --version2Fix
Use absolute paths built with path.resolve, as every example in the docs does.
const path = require('path');
module.exports = {
resolve: {
alias: { '@': path.resolve(__dirname, 'src') },
},
};3Verify
The same import resolves; update both files together from now on.
npx webpack --mode developmentConfirmed by webpack.js.org
Cause 3 of 4
The alias points at a file, so sub-paths fail
1Check
In the docs, an alias whose value is a file path makes a sub-path import an error, while a key ending in a dollar sign matches only the exact request.
grep -n -B1 -A6 "alias" webpack.config.*2Fix
Point the alias at a directory when you import files under it, and use the dollar-suffixed key only for exact matches.
resolve: {
alias: {
Utilities: path.resolve(__dirname, 'src/utilities/'),
xyz$: path.resolve(__dirname, 'path/to/file.js'),
},
},3Verify
Both import 'Utilities/utility' and import 'xyz' resolve.
npx webpack --mode developmentConfirmed by webpack.js.org
Cause 4 of 4
The wrong tsconfig file is read in a multi-config or monorepo project
1Check
The option accepts a file path or an object with configFile and references.
ls tsconfig*.json2Fix
Point it at the right file, and set references to auto when project references are used.
resolve: {
tsconfig: {
configFile: './tsconfig.app.json',
references: 'auto',
},
},3Verify
The aliases from that file now resolve.
npx webpack --mode developmentConfirmed by webpack.js.org
How do I stop it coming back?
- Define each alias in one place, and generate the other from it, or rely on resolve.tsconfig.
- Use absolute paths in resolve.alias.
- Add an import through each alias to a smoke test that runs the build.
Sources
How was this page made?
I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.
Which stack is behind this page?
Projects of mine built on the same technologies:
- TaxiDexMy own multi-tenant taxi dispatch SaaS: API, dispatcher portal, driver and passenger apps, and the servers underneath.
- QistLockA NestJS and React SaaS driving an Android Device Owner agent that locks financed phones when payments lapse.
- WorkforceA field app, an admin console and a self-hosted Node.js server for push and reconciliation.
Related fixes
Web apps
webpack does not find your .ts and .tsx files
Can't resolve
Webpack tries only .js, .json and .wasm unless told otherwise, and it needs a loader before it can read TypeScript.
3 causes, each with a fixWeb apps
tsconfig rejects allowImportingTsExtensions
An error that allowImportingTsExtensions needs noEmit or emitDeclarationOnly
allowImportingTsExtensions lets files import each other with .ts or .tsx extensions, and TypeScript only allows it together with noEmit or emitDeclarationOnly.
2 causes, each with a fixWeb apps
Cypress refuses to start with 'Your configFile is invalid'
Your configFile threw an error from: /path/to/cypress.config.ts
Cypress could not load cypress.config.js or .ts, or found something wrong in it.
5 causes, each with a fixWeb apps
ESLint cannot decide which copy of the @typescript-eslint plugin to use
The message lists two file paths for the same plugin, each with the name of the config that loaded it
ESLint found the same plugin at two different file paths and will not pick one.
3 causes, each with a fixWeb apps
ESLint says it cannot resolve a path to a module that does exist
Unable to resolve path to module 'react'. import/no-unresolved
import/no-unresolved fails when eslint-plugin-import cannot find the file or package on disk with its resolver.
4 causes, each with a fixWeb apps
ESLint was configured to run using parserOptions.project, but the file is not in the TSConfig
However, that TSConfig does not include this file
Type-aware linting needs every linted file to belong to a TypeScript project.
4 causes, each with a fix