Building a component-based project, like with React’s Next.js framework, requires importing modules or component files to create an entire user interface.
When we import modules to use in a file, we must know how to determine where the imported modules are located in relation to the current file. To do this, we must understand what relative and absolute imports are.
In this lesson, we will discuss relative and absolute imports and learn how to implement them in a Next.js application. We will cover:
In a relative import, the file’s import path should be relative to where the import statement is. Relative imports generally start with ./
, ../
, and so on.
Let’s consider a typical Next.js file structure:
project ├── components │ ├── Footer.js │ ├── Header.js │ └── Layout.js
Usually, when we have files like Header.js
and Footer.js
containing content that we can share across multiple pages, we would import them into a Layout.js
file to compose the web pages. If we import those component files correctly in Layout.js
, we will have the following imports in the top section like so:
import Header from './Header'; import Footer from './Footer';
The file extension defaulted to .js
, so we ignored it in the file path.
Now, let’s break down the path in ''
:
Adding ./
in the path means JavaScript will look for a file relative to the “current” directory. This is because the Header.js
and Footer.js
files live in the same folder as the Layout.js
— in this case, the components
folder.
Also, we have a pages/_app.js
file in Next.js that lets us use the Layout
component to wrap the top-level Component
. So, let’s consider the following updated structure:
project ├── components │ ├── Footer.js │ ├── Header.js │ └── Layout.js │── pages │ ├── _app.js │ ├── ...
Now, importing the Layout
component of the Layout.js
file inside the pages/_app.js
file will look like so:
import Layout from '../components/Layout';
Using ../
in the relative file path inside the pages/_app.js
file lets us step out from the current directory — pages
— so we can go into the components
folder to access the Layout.js
file.
Let’s see another example. Imagine we have the following file structure:
project ... │── pages │ ├── blog │ │ │── index.js │ │ └── ... │ ├── _app.js │ ├── ... │── styles │ ├── Blog.module.css │ ├── ...
Let’s break down how we can import the Blog.module.css
file inside the pages/blog/index.js
file:
First, we will step out of the current directory — the blog
directory — and move into the parent directory — pages
— using ../
in our file path.
Then, from the pages
directory, we will also step out into its parent directory — the root — so the relative path now looks like so: ../../
.
We will then go into the styles
directory from the root, so the path looks like ../../styles
.
Finally, we can access the Blog.module.css
, so we have: ../../styles/Blog.module.css
.
If we put the above steps into action, the import and file path will look like so:
import styles from '../../styles/Blog.module.css';
In summary, we use ./
in a file to reference a module that lives in the same directory as that file. Likewise, we use ../
in a file to reference a module that lives in the parent directory, ../../
in a file to reference a module in the directory above the parent, and so on.
Relative imports are not always friendly. Actually, they can be quite confusing! As we’ve seen above, we had to keep careful track of the level of the directory we are currently in.
Additionally, relative imports can result in a poor developer experience, especially in a complex project. If our application grows, we may end up getting a path that looks like so:
'../../../styles/Blog.module.css';
The path can look even more complex for a very deeply nested path.
The problem may worsen if we change the file location, as this may require us to update the file paths. To improve the developer experience, we will learn how to configure a Next.js project to support absolute imports.
An absolute import provides a straightforward way to import modules. This import type specifies a path starting from the project’s root.
Now, instead of worrying about keeping track of directory levels like so, as in the case of relative imports:
'../../../styles/Blog.module.css';
We will have a cleaner way that looks like this:
'styles/Blog.module.css';
In the code above, I am assuming that the styles
directory exists at the project root.
We can also use an alias that looks like so:
'@styles/Blog.module.css';
Let’s take a closer look at using absolute imports in a Next.js project.
jsconfig.json
fileThe jsconfig.json
file lets us specify a base directory for a project. Since version 9.4, Next.js allows us to use this file to identify the root files and perform path mapping needed for absolute imports.
To get started, we will create a jsconfig.json
in the root of our project and add the following configuration:
{ "compilerOptions": { "baseUrl": "." } }
Note that if we were using TypeScript, we would add the code in tsconfig.json
instead.
The baseUrl
option lets us specify the base directory to resolve modules. By assigning a .
, JavaScript or TypeScript will look for files starting in the same directory as the jsconfig.json
— that is, the root directory.
For that reason, our earlier relative import example, which looked like this:
import styles from '../../styles/Blog.module.css';
Will now look like the following:
import styles from 'styles/Blog.module.css';
Again, in the code above, I am assuming that the styles
directory exists at the project root.
Note that anytime we modify the jsconfig.json
or tsconfig.json
files, we must restart the dev server.
baseUrl
It is common for developers to create a src
folder in the project root to hold the working files. Let’s consider the following structure:
project ... │── src │ ├── components │ │── pages │ │── styles │ │── ... │ │── jsconfig.json
In this case, we can tell JavaScript or TypeScript to look for files starting at the src
folder by updating the baseUrl
to point to src
:
{ "compilerOptions": { "baseUrl": "src" } }
The src
directory as specified in the file must be relative to the project root. Now, this update will allow absolute imports from the src
directory.
For more significant projects with different levels of deeply nested directories containing files, we may want to create custom module aliases to match different directories instead of matching only the base directories.
Consider the following structure:
project ... │── src │ ├── components │ │ │── homePage │ │ │ │── Hero.js │ │ │ │── Testimonial.js │ │ │ │── ... │ │ │── blogPage │ │ │── ... │ │── pages │ │ │── index.js │ │ │── ... │ │── styles │ │── ... │ │── jsconfig.json
By using a relative import, as we’ve learned, we can import the Testimonial.js
component file from inside pages/index.js
like so:
import Testimonial from '../components/homePage/testimonial'
We also learned to simplify the above process using the absolute import, so we have the following:
import Testimonial from 'components/homePage/testimonial'
Now, by configuring module aliases, we can further simplify the absolute import so we can have the following:
import Testimonial from '@homePage/testimonial'
Let’s explore how to do so using a paths
option.
paths
optionAdding a paths
option in the configuration lets us configure module aliases. Considering the file structure above, we will update the config file to include paths
entries. By starting from the root, the jsconfig.json
file will look like so:
{ "compilerOptions": { "baseUrl": ".", "paths": { "@homePage/*": ["src/components/homePage/*"], "@blogPage/*": ["src/components/blogPage/*"], "@styles/*": ["src/styles/*"], } } }
The paths
object contains entries that are resolved relative to the baseUrl
. In the above code, the entries are relative to the project root.
If we specify the src
as the baseUrl
, the path entries will look like so:
{ "compilerOptions": { "baseUrl": "src", "paths": { "@homePage/*": ["components/homePage/*"], "@blogPage/*": ["components/blogPage/*"], "@styles/*": ["styles/*"], } } }
In this case, the entries are relative to the src
directory, which is then relative to the project root. Either of the above code blocks will work.
The above configuration creates path aliases for all files in the:
homePage
folder using @homePage
blogPage
folder using @blogPage
styles
folder using @styles
So instead of using components/homePage/Hero
, we would use @homePage/Hero
. Code editors like VS Code will also know how to provide proper IntelliSense for path autocomplete.
If you’ve followed this lesson up to this moment, you shouldn’t experience issues with absolute imports. However, we will mention two steps that often help resolve or prevent some common pitfalls that users run into while configuring Next.js for absolute imports.
First, we must ensure that our Next.js version is at least v9.4. Then, we must always restart the Next.js project if we modify the jsconfig.json
config file.
Following these two steps should keep you from running into issues with Next.js absolute imports not working, or help you resolve existing errors.
So far, we’ve covered all we need to know regarding relative and absolute imports. This section will implement what we’ve learned in a Next.js application.
In a different blog post, we discussed how to add an RSS feed to a Next.js app. In that lesson, we worked with a Next.js project that used a relative import to load files. We will refactor the module’s path to use absolute imports.
Let’s clone the project and follow the steps to support absolute imports after.
Clone the project using the following command:
git clone https://github.com/Ibaslogic/nextjs-mdx-blog-rss
Next, cd
into the project and run the command that installs dependencies to the local node_modules
folder:
cd nextjs-mdx-blog-rss npm install # or yarn
Finally, run the project:
npm run dev # or yarn dev
The project should be up and running at http://localhost:3000.
If we open the source code, we should have a file structure closer to the following:
nextjs-mdx-blog-rss ... ├── components │ ├── Footer.js │ ├── Header.js │ ├── Layout.js │ └── MdxComponents.js ├── pages │ ├── api │ ├── blog │ │ ├── [slug].js │ │ └── index.js │ ├── _app.js │ ├── ... │ └── index.js ├── posts ├── public ├── styles ├── utils │ ├── generateRSSFeed.js │ ├── mdx.js ├── menuItems.js ...
If we navigate the project folder and open the files, we have used relative imports to include file content in another file. To add support for absolute imports, we’ll use the following steps.
First, add a jsconfig.json
file in the root of the project and add the following code:
{ "compilerOptions": { "baseUrl": "." } }
Next, save the file and restart the dev server.
We can now define absolute imports from the project’s root with the above code. In other words, all the imports are now relative to the project’s root. So, we can now import modules directly from the root directories like components
, styles
, and utils
.
For instance, look for MDXComponents
import in the blog/[slug].js
file and update from using a relative import, which is shown below:
import MDXComponents from '../../components/MdxComponents';
…to instead use an absolute import, like so:
import MDXComponents from 'components/MdxComponents';
Let’s do the same for the other imports. We will configure an optional module alias from the next step to further simplify absolute imports.
Let’s open the jsconfig.json
file and update the configuration so we have the following:
{ "compilerOptions": { "baseUrl": ".", "paths": { "@components/*": ["components/*"], "@styles/*": ["styles/*"], "@utils/*": ["utils/*"], } } }
We’ll save the file and restart the dev server.
Now, we can specify a path like so:
import MDXComponents from '@components/MdxComponents';
Instead of this:
import MDXComponents from 'components/MdxComponents';
Let’s again do the same for the other imports. We’ll need to follow the next three steps if we want to put the working files in an optional src
folder.
Create a src
folder in the project root and move the components
, pages
, styles
, and utils
folders, along with the menuItems.js
file, inside the src
folder.
Next, update the configuration baseUrl
to point to the src
:
{ "compilerOptions": { "baseUrl": "src", "paths": { "@components/*": ["components/*"], "@styles/*": ["styles/*"], "@utils/*": ["utils/*"], } } }
Restart the dev server.
Let’s ensure the project works as expected. See the final project source code here.
As we’ve learned, relative imports don’t need any configuration like absolute imports. However, relative imports can sometimes be confusing and may result in a poor developer experience. We have a more precise and concise way to import modules in Next.js with absolute imports.
In this lesson, we discussed relative and absolute import types and how to implement them in a Next.js project. I hope you enjoyed reading this guide. If you have any thoughts, you can share them in the comment section.
Debugging Next applications can be difficult, especially when users experience issues that are difficult to reproduce. If you’re interested in monitoring and tracking state, automatically surfacing JavaScript errors, and tracking slow network requests and component load time, try LogRocket.
LogRocket is like a DVR for web and mobile apps, recording literally everything that happens on your Next.js app. Instead of guessing why problems happen, you can aggregate and report on what state your application was in when an issue occurred. LogRocket also monitors your app's performance, reporting with metrics like client CPU load, client memory usage, and more.
The LogRocket Redux middleware package adds an extra layer of visibility into your user sessions. LogRocket logs all actions and state from your Redux stores.
Modernize how you debug your Next.js apps — start monitoring for free.
Would you be interested in joining LogRocket's developer community?
Join LogRocket’s Content Advisory Board. You’ll help inform the type of content we create and get access to exclusive meetups, social accreditation, and swag.
Sign up nowFix sticky positioning issues in CSS, from missing offsets to overflow conflicts in flex, grid, and container height constraints.
From basic syntax and advanced techniques to practical applications and error handling, here’s how to use node-cron.
The Angular tree view can be hard to get right, but once you understand it, it can be quite a powerful visual representation.
In this post, we’ll compare Babel and SWC based on setup, execution, and speed.
2 Replies to "Understanding relative and absolute imports in Next.js"
The way Vercel recommends to do an absolute imports is to use “@/“ like “@/styles”. With this syntax we can differentiate an absolute import from a scoped third party dependency. Sadly create-react-app is by default configured with the “@syntax”. I asked for this to change in this discussion: https://github.com/facebook/create-react-app/discussions/12666 plz upvote ^^
Hi Fredericrous,
Thanks for reading. Alias is simply a pseudonym, i.e., an assumed identity. So either way is acceptable for absolute imports. Thank you!