How to setup path aliases for development with Next.js & Jest
5 min read
I love Next.js and I wanted to share how you can setup path aliases for your imports. Sometimes you end up with various levels of file nesting and this can get messy fast.
Fortunately for us both Next.js and Jest support adding path aliases so we don't end up with something like this 👇
import Component from "../../../Component/Component";
For any medium to large react project you will have realized that due to the component nature of the library we end up doing a lot of importing. Let's find out how we can change the above into this 👇
import Component from "@/Component/Component";
for both development in Next.js and for our tests using the test Framework Jest.
Let's start with Next.js 😄
Step 1 - Create a Next app
I'll start with a brand new project so you can see all the steps. For this I will create a new Next application using
create-next-app so we can get up and running quickly. Start by running
npx create-next-app. This is the basic file structure that comes with
Step 2 - Create some files to import
Next I'm going to create a
src folder which is where I normally store the apps components, hooks etc. Let's add some files to our
src folder to simulate how a real project might look 👇 .
Here I have created the following files
Button.jscomponents inside a
__tests__folder with our component test files
useStorage.jshook inside a
The contents of the files is not important. As long as you export something from your components which I will show you in a second.
Step 3 - Specify our path aliases
First we need to create a
jsconfig.json file (or
tsconfig.json if you're using TypeScript) and setup our path aliases. My setup looks like this 👇.
Here we can specify a base url that we start our import from. Commonly you will see the root
Next we can specify path aliases for our paths to the different folder locations.
paths is an object where we start with our path alias and assign it an array of paths. A common syntax of alias is in the format
"@/fileName/" but you can use anything you'd like.
Let's take our
components alias as an example. We are saying we want to match the alias
"@/components/" to the path
Step 4 - Checking that our aliases work
Now let's add some basic code to our components:
and the header is the same except it exports a
<h2 /> tag 🙂. We can import them into other pages/components using the path aliases like this 👇.
And to show you everything is working as expected in the browser 👇.
Beautiful am I right 😉.
If we had code in our other files that we created inside our
lib files we could import them like this 👇
Of course we don't have anything in there but I wanted to show this is how you would import from those places 👏.
Step 1 - Install and configure the necessary files
I wanted to add this extra step for two reasons
- You should be testing your apps
- It's good to keep your imports consistent across development code and tests
First let's download the packages we need to work with Jest. I will install the following packages:
jest if the primary package we need to install in order to use the Jest testing framework. While
babel-jestwill help transform our code so we can include things like ES modules
import syntax in our test files.
We also have to configure a
.babelrc file with the following setup 👇
What we are doing here is telling babel to use the custom preset for Next.js.
Next I'll add a
test script to the
package.json file so we can run our test suites like this 👇
Step 2 - Add our
Finally we can now get on to our aliases in Jest 👏. We first need to create a
jest.config.js file. There are a couple of options we will pass in here and it looks something like this 👇.
The first thing we do is use the
testPathIgonrePattern which is defined as an array of strings that specify which paths we would like to skip when testing. Here we include the
node_modules directory and the
.next directory which contains our build files.
We don't want Jest looking in these directories for tests and we specify these paths starting at the root
Next comes our path aliases. We need to use the
moduleNameMapper property to map our aliases. It is a map of regular expressions and in this case we setup our three current aliases of
You can do this for any path you are likely to be importing regularly. If you wanted to move on to integration tests and import you pages into tests you could do the same for example
The order in which you setup these aliases could matter however. These patterns are checked by Jest from top to bottom therefore you have more specific rules you should include them first.
For more information check out the Jest - Configuring Jest.
Now if we add an empty test block to one of our files and attempt the import with the alias we won't receive any errors after running out test script. Our imports are now working as expected in Jest ✔.
Now you can actually start doing some work 😄.
I hope this quick setup was able to help. I think we can all agree that adding path aliases leads to nicer imports and cleaner code!
If you have any questions or comments let me know @Kieran6dev or in the comments below. I love hearing from you all!
if you feel like you need to support my content other than just reading or talking with me you can do so though Buy me a coffee below.
See you soon 👋
Did you find this article valuable?
Support Kieran Roberts by becoming a sponsor. Any amount is appreciated!