# How to Configure a Next.js Import Alias in next.config.js

> Learn to configure a Next.js import alias in next.config.js using resolveAlias for Turbopack or webpack alias for Webpack. Simplify your imports and boost development efficiency.

- Repository: [Vercel/next.js](https://github.com/vercel/next.js)
- Tags: how-to-guide
- Published: 2026-02-21

---

**Configure a Next.js import alias by adding a `resolveAlias` object to [`next.config.js`](https://github.com/vercel/next.js/blob/main/next.config.js) for Turbopack, or by extending `webpack.resolve.alias` in the webpack configuration function for legacy Webpack builds.**

Next.js allows you to rewrite module import paths using aliases, enabling cleaner, more maintainable imports across your codebase. Whether you are using the modern Turbopack compiler or the legacy Webpack bundler in the [`vercel/next.js`](https://github.com/vercel/next.js/blob/main/vercel/next.js) repository, the configuration syntax differs slightly but follows the same underlying principles as Webpack's `resolve.alias` option.

## Turbopack Method: Using `resolveAlias`

For projects using Turbopack (the default in recent Next.js versions), you declare aliases directly in the root configuration object. According to the source code in [`crates/next-core/src/next_config.rs`](https://github.com/vercel/next.js/blob/main/crates/next-core/src/next_config.rs), the `resolveAlias` field is parsed by the `resolve_alias_options()` method and converted into an internal `ResolveAliasMap` structure [⟨source⟩](https://github.com/vercel/next.js/blob/canary/crates/next-core/src/next_config.rs#L1722-L1730).

Add your mappings to [`next.config.js`](https://github.com/vercel/next.js/blob/main/next.config.js) like this:

```javascript
// next.config.js
/** @type {import('next').NextConfig} */
const nextConfig = {
  resolveAlias: {
    // Maps '@components' to the local components directory
    '@components': './src/components',
    
    // Redirect a third-party library to a local shim
    'lodash': './src/shims/lodash',
  },
};

module.exports = nextConfig;

```

When you import `@components/Button`, Turbopack resolves it to `./src/components/Button` relative to your project root. The alias map is validated during the build process to ensure paths are reachable.

## Webpack Method: Extending `webpack.resolve.alias`

If you are using the legacy Webpack compiler or need to programmatically construct aliases, modify the webpack configuration via the `webpack` function in [`next.config.js`](https://github.com/vercel/next.js/blob/main/next.config.js):

```javascript
// next.config.js
const path = require('path');

module.exports = {
  webpack: (config) => {
    config.resolve.alias = {
      ...config.resolve.alias,
      '@app': path.join(__dirname, 'src/app'),
      'react': path.join(__dirname, 'patches/react'),
    };
    return config;
  },
};

```

This approach merges your custom aliases with Next.js's internal webpack configuration. Be aware that if you attempt to override private Next.js internal modules or pages, the build will abort with a validation error defined in [`packages/next/src/build/webpack-build/impl.ts`](https://github.com/vercel/next.js/blob/main/packages/next/src/build/webpack-build/impl.ts) [⟨source⟩](https://github.com/vercel/next.js/blob/canary/packages/next/src/build/webpack-build/impl.ts#L362).

## Using Import Aliases in Application Code

Once configured, use your aliases in any JavaScript or TypeScript file:

```tsx
// pages/index.tsx
import Header from '@components/Header';
import Button from '@components/ui/Button';
import customReact from 'react';

export default function Home() {
  return (
    <div>
      <Header />
      <Button>Click me</Button>
    </div>
  );
}

```

The bundler automatically remaps these imports during the module resolution phase, ensuring that `@components` resolves to your specified directory regardless of where the importing file is located in the project tree.

## Validation and Error Handling

Next.js validates import aliases at build time to prevent critical conflicts. The system specifically guards against aliases that would override internal Next.js pages or core modules. If you define an illegal alias, the build process emits a descriptive error message referencing the conflicting path and provides a link to the documentation for resolution. This validation logic resides in the webpack build implementation and applies to both Turbopack and Webpack configurations.

## Summary

- Declare **Turbopack aliases** using the `resolveAlias` object in [`next.config.js`](https://github.com/vercel/next.js/blob/main/next.config.js), processed by [`crates/next-core/src/next_config.rs`](https://github.com/vercel/next.js/blob/main/crates/next-core/src/next_config.rs).
- Declare **Webpack aliases** inside the `webpack` configuration function by extending `config.resolve.alias`.
- Both methods create an internal import map that redirects module requests to your specified file system locations.
- Invalid aliases that conflict with Next.js internals trigger build-time errors with helpful debugging information.

## Frequently Asked Questions

### What is the difference between `resolveAlias` and `webpack.resolve.alias`?

**`resolveAlias`** is the native Turbopack configuration option that mirrors Webpack's behavior but is processed by the Rust-based compiler core. **`webpack.resolve.alias`** is the traditional Webpack-specific configuration used when running Next.js with the `--turbo` flag disabled or when forcing Webpack mode. Both achieve the same result but target different bundlers within the Next.js ecosystem.

### Can I override Next.js internal modules with import aliases?

No, the build system explicitly prevents you from overriding private Next.js pages or internal modules. If you attempt to alias a reserved path, the build aborts with a validation error generated in [`packages/next/src/build/webpack-build/impl.ts`](https://github.com/vercel/next.js/blob/main/packages/next/src/build/webpack-build/impl.ts) to prevent runtime conflicts and ensure framework stability.

### Do TypeScript path mappings conflict with Next.js import aliases?

TypeScript `paths` configuration in [`tsconfig.json`](https://github.com/vercel/next.js/blob/main/tsconfig.json) provides IDE autocompletion and type checking, while [`next.config.js`](https://github.com/vercel/next.js/blob/main/next.config.js) aliases control the actual bundler resolution. For best results, keep both configurations in sync so that TypeScript can resolve the same paths that the Next.js compiler will use during the build.

### Where does Next.js process import alias configuration?

Turbopack aliases are processed in [`crates/next-core/src/next_config.rs`](https://github.com/vercel/next.js/blob/main/crates/next-core/src/next_config.rs) by the `resolve_alias_options()` function, which converts your JavaScript object into a `ResolveAliasMap`. Webpack aliases are processed by the webpack configuration pipeline in [`packages/next/src/build/webpack-build/impl.ts`](https://github.com/vercel/next.js/blob/main/packages/next/src/build/webpack-build/impl.ts), which validates the aliases before incorporating them into the final webpack configuration.