Next.js Absolute Imports and Aliases

Since Next.js v9.4 you have the ability to use absolute imports or aliases for your import statements. I love this feature with all my heart.

When working on a large project you end up with the spaghetti import statements like ./../../../../. This happens because your folder structure grows and you end up importing files from here and there.

With Next.js v9.4 you can do away with the spaghetti import statements using either the absolute imports or by creating aliases. This would change the following import statement from

BEFORE#

import Heading from '../../../../components/heading'

AFTER#

import Heading from 'components/heading'

Let’s see how to implement this.

Next.js Absolute Imports#

Basically you only need to make Next.js aware of the project baseUrl which can be configured via jsconfig.json (JS projects) or tsconfig.json (TS projects). That’s about it.

1. Create a jsconfig.json or tsconfig.json file
2. Add compilerOptions object with the baseUrl

// Your jsconfig.json or tsconfig.json
{
  "compilerOptions": {
    "baseUrl": "."
  }
}

Here . defines the base URL of the project to be the root directory.

So, if you have a directory called components in the root of your project, you can then import directly from that directory without any spaghetti import statements. This is very well integrated with editors like VSCode.

Now you can import components like this:

import Heading from 'components/heading'

But what if you want to define fancy aliases to these directories you have?

Next.js Aliases#

Next.js import aliases help you define, well aliases to paths in your project. WTFOMGBBG is that? Well, allow me to explain.

Imagine you have a layout system and all the layout components are inside the components/Layout directory. Even if you define the absolute URLs you would still end up writing long import statements like the following:

import Container from 'components/Layout/Container';

But in addition the baseUrl you can define a paths option which allows you to create custom module aliases.

// Your jsconfig.json or tsconfig.json file.
{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/layout/*": ["components/Layout/*"]
    }
  }
}

Now that we have defined the @/layout/ alias for all the files in the components/Layout/ directory, you can import them like this:

import Container from '@/layout/Container';

⚠️ REMEMBER:

1. You must specify baseUrl if you specify paths. You can learn more about the paths option in the TypeScript documentation.
2. If you have the next dev running when you define a new path, make sure to restart next dev.

Peace! ✌️