Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Next.js and React

A path alias works in the editor but not in the webpack build

ErrorModule not found

Short 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.

  • Applies to webpack 5.105, TypeScript 5.7, Node.js 22
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 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.*
  2. 2Match what you see, then jump to its fix

    1. 1tsc and the editor accept the import, but the bundler cannot resolve it.webpack was never told about compilerOptions.pathsFix
    2. 2npx 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. 3import 'xyz' works but import 'xyz/file.js' does not.The alias points at a file, so sub-paths failFix
    4. 4tsconfig: true is set, yet paths from tsconfig.app.json are ignored.The wrong tsconfig file is read in a multi-config or monorepo projectFix

What does the error look like?

  • Module not found
  • Can'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 --version

2Fix

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 development

Confirmed by webpack.js.org

Did this fix it?

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 --version

2Fix

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 development

Confirmed by webpack.js.org

Did this fix it?

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 development

Confirmed by webpack.js.org

Did this fix it?

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*.json

2Fix

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 development

Confirmed by webpack.js.org

Did this fix it?

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:

Related fixes

Web 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 fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.