Ahmad Awais



Next.js Absolute Imports and Aliases

Ahmad AwaisAhmad Awais
Nextjs Absolute Import 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


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


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';


  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! ✌️

I help businesses understand developers 📟 Just launched Node.js CLI Automation Course 👨‍🏫 Edutainer at VSCode.pro 🎩 An award-winning GitHub Star open-source engineer & advocate 🦊 Google Developers Expert Web DevRel 🌳 Node.js foundation Community Committee Outreach Lead ✌️ Author of various open-source dev-tools and software libraries used by millions of developers worldwide ⓦ WordPress Core Developer 📣 TEDx Speaker 🙌 Leading developers and publishing technical content for over a decade 💜 Loves his wife (Maedah) ❯ Learn more →

Say 👋 on Twitter @MrAhmadAwais | Subscribe to the Developers Takeaway!


Developers Takeaway

Takeaway my professional opinion on open-source, developer relations, growing your business with family, and everything in between! Delivered to your inbox a couple of times every year. I'm even funny at times. I hate spam — pinky-promise!

👨‍💻👩‍💻 118,947 Developers Already Subscribed
Comments 0
There are currently no comments.