Maaz Zindani

Loading the index…

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

A tsconfig paths alias is not found by TypeScript or by the build

ErrorAn import such as @/components/button is underlined in the editor

Short answer

The paths option only tells TypeScript how to find types; it does not change emitted imports. First check the targets: they are relative to baseUrl, or to tsconfig.json when baseUrl is unset. Then give the bundler or test runner the same alias: Vite resolve.alias, webpack resolve.alias or Jest moduleNameMapper.

  • Applies to TypeScript 5.x, Vite, webpack 5, Jest, Next.js
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Open the tsconfig.json that covers the failing file and read its paths and baseUrl entries. Every cause below starts from them.

    grep -n -A6 "paths\|baseUrl" tsconfig.json
  2. 2Match what you see, then jump to its fix

    1. 1The alias target names a folder that does not exist from the base folderThe paths target does not point at the real folderFix
    2. 2tsc passes but the dev server or build cannot resolve the importThe bundler does not read paths (Vite or webpack)Fix
    3. 3The app runs, but tests fail to resolve the importThe test runner does not know the alias (Jest)Fix
    4. 4A webpack build, not a Vite one, fails on the aliaswebpack has no matching resolve.aliasFix

What does the error look like?

  • An import such as @/components/button is underlined in the editor
  • tsc is happy but the dev server or the test runner cannot find the same import

Cause 1 of 4

The paths target does not point at the real folder

1Check

paths targets are relative to baseUrl if it is set, otherwise to the tsconfig file. A src/ folder missing from the target is the usual slip.

ls src/components

2Fix

Make the target match the folder from the right base.

{
  "compilerOptions": {
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}

3Verify

Restart the TypeScript server and check the import no longer has a squiggle, then run the type check.

npx tsc --noEmit

Confirmed by typescriptlang.org

Did this fix it?

Cause 2 of 4

The bundler does not read paths (Vite or webpack)

1Check

The TypeScript docs say paths does not change how imports are emitted, so another tool must apply the mapping at bundle time.

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

2Fix

Add the same alias to the bundler config. Vite advises absolute file system paths for aliases.

// vite.config.ts
import path from 'node:path';
import { defineConfig } from 'vite';

export default defineConfig({
  resolve: {
    alias: { '@': path.resolve(__dirname, 'src') },
  },
});

3Verify

Start the dev server and open a page that uses the alias.

npm run dev

Confirmed by vite.dev

Did this fix it?

Cause 3 of 4

The test runner does not know the alias (Jest)

1Check

Jest has its own resolver. It maps module names with regular expressions in moduleNameMapper.

grep -rn "moduleNameMapper" jest.config.*

2Fix

Add an anchored pattern that maps the alias to the folder with <rootDir>.

// jest.config.js
module.exports = {
  moduleNameMapper: {
    '^@/(.*)$': '<rootDir>/src/$1',
  },
};

3Verify

Run the tests.

npx jest

Confirmed by jestjs.io

Did this fix it?

Cause 4 of 4

webpack has no matching resolve.alias

1Check

webpack uses resolve.alias and gives it precedence over other module resolution.

grep -n "alias" webpack.config.*

2Fix

Add the alias with an absolute path.

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

3Verify

Run the build.

npx webpack

Confirmed by webpack.js.org

Did this fix it?

How do I stop it coming back?

  • Define each alias twice on purpose: once in tsconfig for types, once in the tool that runs the code.
  • Use Next.js when you want one source of truth: it supports the paths and baseUrl options of tsconfig.json itself.
  • Anchor Jest patterns with ^ and $.

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

Next step

Want this handled for good?

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