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

Configure a Next.js import alias by adding a resolveAlias object to 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 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, the resolveAlias field is parsed by the resolve_alias_options() method and converted into an internal ResolveAliasMap structure ⟨source⟩.

Add your mappings to next.config.js like this:

// 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:

// 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 ⟨source⟩.

Using Import Aliases in Application Code

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

// 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, processed by 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 to prevent runtime conflicts and ensure framework stability.

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

TypeScript paths configuration in tsconfig.json provides IDE autocompletion and type checking, while 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 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, which validates the aliases before incorporating them into the final webpack configuration.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}