Path aliases with TypeScript in Node.js

Published in

Level Up Coding

3 min readJan 17, 2020

In this article, I will walk you through setting up path aliases in your TypeScript project and show you how to clean up your code.

The problem

In Node.js (or TS/JS in general) you can import modules into your code. This might look like the following:

import { User } from '../../user/model';
import { Article } from '../../article/model';import { Cache } from '../../../../cache';
import { MongoDB } from '../../../../mongodb';

Notice these dots ../../ to access parent directories.

The problem we have here is that the deeper your project tree is, the more ../ are required to access modules in higher layers. This doesn’t look very clean to be honest, it’s difficult to understand, and it can make any code reorganization very painful. Fortunately we can change that.

The solution: path aliases

What are path aliases?

In TypeScript, you can avoid these “bad” looking imports with the help of path aliases. With path aliases, you can declare aliases that map to a certain absolute path in your application.

Here a quick example:

import { User } from '@components/user/model';
import { Article } from '@conponents/article/model';import { Cache } from '@services/cache';
import { MongoDB } from '@services/mongodb';

In this case, the two aliases are

@components that maps to ‘./src/api/components’
@services that maps to ‘./src/services’

Setup

Let’s get into it and set up some path aliases. Assume we have a Node.js app with the following project structure:

my-node-app
└───src
   │
   └───api
   │   │
   │   └───components
   │   │   │
   │   │   └───article
   │   │   │
   │   │   └───user
   │   │
   │   │   server.ts
   │
   │
   └───services
   │   │    cache.ts
   │   │    mongodb.ts
   │    
   │   index.ts

Step 1: Update tsconfig.json

First of all, we have to declare the path aliases in our tsconfig.json file:

"baseUrl": "./src",
"paths": {
    "@components/*": ["api/components/*"],
    "@services/*": ["services/*"]
}

Now you can use the new path aliases for module imports in your application. There shouldn’t occur any errors in your IDE / Editor (in my case VSC) or when you compile the code.

However, we are not done yet. As I said when you try to compile the TS code into JS you won’t see any errors. But as soon as you run your compiled JS code, you will get an error. For example:

Error: Cannot find module ‘@components/user’

That’s because JS can’t resolve the modules for the declared path aliases.

Step 2: Install module-alias package

Next, we’ll install a npm package called module-alias.

npm i --save module-alias

This module registers the path aliases in the compiled JS files. Therefore, we need to make some changes to our package.json:

"_moduleAliases": {
    "@components": "dist/api/components",
    "@services": "dist/services"
  }

Note that ‘dist’ is the folder where the compiled JS files are located.

Last but not least we have to register the path aliases in our application.
Add the following line to the top of your startup file:

import 'module-alias/register';

That’s it! Finally, when you compile and execute the code you shouldn’t see any import errors.

This article was originally published on my blog. Have a look.