Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Node.js, PHP and APIs

A webpack resolve.alias that does not resolve the import you expect

ErrorModule not found: Error: Can't resolve 'Utilities/utility'

Short answer

Webpack aliases are matched by prefix and used exactly as written. An alias that points at a file breaks every subpath import, a trailing $ turns the alias into an exact match, and a config that relies on the working directory breaks elsewhere. Point the alias at a folder and build it with path.resolve.

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

Fix it fast

  1. 1Find out which cause you have

    Read the full error first: it names the request that failed and the directory it was imported from. Then list every alias in the config so you can match the failing request against them.

    npx webpack 2>&1 | grep -A3 "Can't resolve"
    grep -n -A8 "alias" webpack.config.*
  2. 2Match what you see, then jump to its fix

    1. 1import 'xyz' works, but import 'xyz/file.js' gives Module not found.The alias points at one file, so subpath imports failFix
    2. 2import 'xyz' resolves, but import 'xyz/sub' falls back to node_modules and fails.The alias key ends in $ and only matches the bare nameFix
    3. 3The alias resolves when you run webpack from the project root, and fails from a CI step, a subfolder or a monorepo script.The config depends on the folder webpack was started fromFix
    4. 4An import from node_modules starts failing after you added an alias with a common name.The alias hides a real package of the same nameFix

What does the error look like?

  • Module not found: Error: Can't resolve 'Utilities/utility'
  • Module not found: Error: Can't resolve '@/components/Button'

Cause 1 of 4

The alias points at one file, so subpath imports fail

1Check

In the behaviour table of the docs, an alias whose target is a file makes the subpath form an error, while a target that is a directory serves both.

grep -n -A8 "alias" webpack.config.*

2Fix

Make the alias point at the directory. Use an exact-match key with $ only where you really want the bare name to map to one file.

const path = require('path');
module.exports = {
  resolve: {
    alias: {
      Utilities: path.resolve(__dirname, 'src/utilities/'),
    },
  },
};

3Verify

Rebuild; import Utility from 'Utilities/utility' now resolves.

npx webpack

Confirmed by webpack.js.org

Did this fix it?

Cause 2 of 4

The alias key ends in $ and only matches the bare name

1Check

A trailing $ marks an exact match. Without it, xyz/file.js is aliased as well.

grep -n '\$:' webpack.config.*

2Fix

Remove the $ when you want the whole prefix aliased.

alias: {
  xyz: path.resolve(__dirname, 'src/xyz'),   // not xyz$
}

3Verify

Rebuild and import a subpath.

npx webpack

Confirmed by webpack.js.org

Did this fix it?

Cause 3 of 4

The config depends on the folder webpack was started from

1Check

The context option defaults to the current working directory of Node.js, and the docs recommend setting it so the config does not depend on that directory. Relative alias targets and paths built from process.cwd() move with it.

pwd
grep -n -E "context|process.cwd|alias" webpack.config.*

2Fix

Set context explicitly and build every alias target with path.resolve and __dirname.

const path = require('path');
module.exports = {
  context: path.resolve(__dirname),
  resolve: {
    alias: {
      Templates: path.resolve(__dirname, 'src/templates/'),
    },
  },
};

3Verify

Run the build from another folder and confirm the alias still resolves.

npx webpack --config ./webpack.config.js

Confirmed by webpack.js.org

Did this fix it?

Cause 4 of 4

The alias hides a real package of the same name

1Check

The docs state that aliases take precedence over other module resolution, so an alias named like an npm package wins over the package.

ls node_modules | grep -x "<alias-name>"

2Fix

Rename the alias to something that is not a package name, or use the $ exact form so only the bare import is redirected.

alias: {
  '@app': path.resolve(__dirname, 'src/'),
}

3Verify

Rebuild and run the page that imports the package.

npx webpack

Confirmed by webpack.js.org

Did this fix it?

How do I stop it coming back?

  • Write alias targets with path.resolve(__dirname, ...) every time.
  • Alias folders, not files, unless you intend to redirect a single bare import.
  • Keep the same aliases in your editor or type-checker settings, so the editor and the bundler agree.

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

Back end

ng serve says it cannot determine the project or target

Cannot determine project for command.

The Angular CLI looked through angular.json for a project that defines the target you asked for (serve, build, test) and found none, or found several and could not pick one.

3 causes, each with a fix

Back end

ng serve cannot find the dev-server builder package

Could not find the implementation for builder @angular/build:dev-server

The builder named in angular.json (for example @angular-devkit/build-angular:dev-server) is looked up as an npm package starting from the workspace root.

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