Improving code readability with Path Aliases

Image by Alvaro Reyes from UnSplash

A couple of months back, some friends and I decided it was time we addressed a problem which we promised to address sometime past. To achieve this, we agreed it was best if we use the agile kanban to build our solution and I was asked to play the role of front-end lead and UI/UX designer. This was because I had more experience in this area than other areas of the software development life-cycle. In this role, I had to review all pull requests coming up on the front-end, periodically go over the codebase for technical debts and also ensure we adhere to best practices.
Two weeks down this path I discovered I was spending more time than I allotted for these reviews. At first, I felt I underestimated my Todo so I increased the time, but every time, I spent more time than I had allotted. So I began to analyze what happens and realised the bulk of that time was spent trying to find dependence files (relative JavaScript modules) that are imported at the top of files. It felt like I was trying to perform some sort of computation (in my head) 😂 to know where these files where located on the codebase as the codebase grew.
Below is a sample of what these import statements would look like.

Component imports without alias

I started researching better ways to import files (relative modules) and stumbled upon path aliases. 🎉 Path aliasing or aliases are preconfigured names used to replace long paths in files and resolve to certain directories on a codebase. There are diverse ways of achieving this ranging from configuring webpack resolve (React), using module-alias and in TypeScript configuring the baseUrl and paths in the tsconfig file. We’ll be looking at these in a bit.

Option One: Configuring webpack resolve

If you’re using webpack, you just have to update the resolve object in your webpack config to change the way webpack resolves (finds) modules on your codebase. You’ll do this by adding an alias property which tells webpack how and where to look for certain names in your imports.

Configuring Webpack for path aliases

Now you can import files and relative modules using the alias.

Component imports using Webpack alias

Option Two: Configuring the tsconfig

If you’re using TypeScript, there are two tsconfig properties to be aware of. These are the `baseUrl` and the `paths` properties.

• baseUrl: is used to tell TypeScript where to start resolving relative imports. This accepts a string which indicates where TypeScript will locate relative modules and files. A common value set for this is “.” which means relative to the tsconfig file. However, most devs prefer to have project modules in an src directory which will be relative to the tsconfig file. For that, the value of the `baseUrl` will be “./src”.
• paths mapping: a lot of times, we have dependencies that are not in the root path of our codebase (relative to the tsconfig file). Irrespective of this, we might still want to alias these modules/dependencies when importing them into our codebase. Using the paths property on the tsconfig provides us with more sophisticated ways of mapping and resolving aliases. Paths mapping will be resolved relative to the baseUrl and not the tsconfig. So if you set you baseUrl to a value such as “./src” then you have to write the paths mappings with “./src/” as the root path for the path mappings. We’ll just see a basic example of this, you can use the official TypeScript docs here to learn more about paths.

Option Three: Using module-alias

If you don’t use webpack nor TypeScript, you can still set up path aliases using the module-alias module/library. Run the following command based on your package manager.

yarn add module-alias

OR

npm install module-alias

Add this to your package.json file and configure your aliases as desired.

Module-alias config to be set up in package.json

Now, one last thing to do. Add this at the entry point of your app, like the index.js . This requires and registers your aliases.

Awesome, you can now import files using your alias. 🎉

Component imports with module-alias alias

Note: The examples above worked in a codebase with the structure below. 👇🏽 Your folder structure might the different or similar, so you’ll have to update the configs to work with your folder structure.

Folder structure examples were tested with

With the introduction of path aliases to our project not only was it able to improve review time, but it also improved code readability, the time it took to onboard into a file and reduced errors due to typos in import statements thereby increasing our productivity. I’ll love to hear your thoughts after trying this out.