Finally, Use Your TypeScript Aliases in Parcel v2

Zach — Sat, 07 May 2022 06:51:04 +0000

Do you have a webpack setup you've labored over, but want to try parcel? Blocked on migration because Parcel doesn't resolve tsconfig aliases?

Now you can, in the spirit of (almost) zero-config. Just install parcel-resolver-tspaths and follow the instructions.

How Parcel is Out-of-the-Box

Parcel is supposed to be a fun zero-config build tool. That bubble bursts when you discover that your TypeScript path aliases force you into tooling-specific configuration yet again.

If we look at the Parcel docs for module resolution and aliases:

Aliases are supported through the alias field in package.json.
...

// package.json
{
  "alias": {
    "react": "preact-compat",
    "react-dom": "preact-compat",
    "local-module": "./custom/modules"
  }
}

But lets not make a mess of things. Tsconfig aliases don't belong in package.json, especially when you can't easily auto-generate them.

You might keep scrolling and see the section titled "TypeScript ~ Resolution", followed by a promising tsconfig.json with some paths, and think they do actually support it. Well, they don't. This issue opened in 2017 leads me to believe they don't plan to.

Enter parcel-resolver-tspaths for Parcel v2.

This plugin finally enables you to use your tsconfig path aliases as-is. Go forth without even more tooling-specific configuration.

Resilient Imports with Auto-Generated TypeScript Aliases

Zach — Fri, 06 May 2022 23:55:11 +0000

If you're not familiar, TypeScript paths allow you to assign an alias to some path in your project. This is especially useful for larger projects.

Working Harder

For example, say you're editing code in a path like components/MyComponent/src/hooks/myHook.ts, and you need to import some services code. Your services code might sit at the project root next to components/. Naively, you might use a relative path like:

import { myService } from '../../../services/my-service'

Import tools will often take care of some dirty work for you, such as updating imports when you move files. This relative path is still fragile, and lends itself to tedious work if you decide to move either the component or the service.

Working Smarter

Now to fix this, you'd add paths in your tsconfig.json like:

{
   "compilerOptions":{
      ...
      "paths":{
         "@services":[
            "services/index"
         ],
         "@services/*":[
            "services/*",
            "services/index"
         ]
      }
   },
   ...
}

which would change your fragile import into something more resilient, that won't break when moved to a new folder:

import { myService } from '@services/my-service'

And the best part is that vscode users will get free path intellisense from these aliases too. You'll be able to ctrl+. and add imports via your aliases.

Make it Even Easier with Automation

But if you're working with a large project, why not spare yourself the work of manually writing globs and copy-pasting your heart out in JSON?

I created tsconfig-paths-autogen (1kB minified, 0 dependencies), which will automatically alias all of your project folders. The big change is moving from tsconfig.json to tsconfig.js. I'll explain how this works.

Suppose this is your project directory structure:

src
├── a
├── b
│   └── c
│       └── d
└── e
    └── f

If you want to alias all of them such that you can:

reference the project root and src,
import index files (with and without an trailing /),
go through to subfolders after an alias

then your paths would look like:

"paths": {
  "@a": ["a/index"],
  "@a/*": ["a/*", "a/index"],
  "@d": ["b/c/d/index"],
  "@d/*": ["b/c/d/*", "b/c/d/index"],
  "@c": ["b/c/index"],
  "@c/*": ["b/c/*", "b/c/index"],
  "@b": ["b/index"],
  "@b/*": ["b/*", "b/index"],
  "@f": ["e/f/index"],
  "@f/*": ["e/f/*", "e/f/index"],
  "@e": ["e/index"],
  "@e/*": ["e/*", "e/index"],
  "@/*": ["./*"],
  "~/*": ["../*"]
}

It's tedious to get all these right and maintain them. So, your new tsconfig.js would generate the paths and export itself to json, something like:

// tsconfig.js
const { generatePaths } = require('tsconfig-paths-autogen');
const { onmyjs } = require('onmyjs'); // or any other tool to export this file to JSON.

module.exports = {
  compilerOptions: {
    ...
    paths: generatePaths(baseUrl, {
      // whatever you'd like to start your aliases with, can be empty.
      rootAlias: '@',
      // how far deep to alias from baseUrl
      maxDirectoryDepth: 2,
      // alias components folder but none under it.
      excludeAliasForSubDirectories: ['components'],
      // aliases for potentially excluded directories
      includeAliasForDirectories: {
        common: 'components/common',
      },
    }),
  }
}
// export to tsconfig.json
onmyjs(module.exports, 'tsconfig.json', true);

Integrating this into your build scripts

So now you're probably asking what to do, because your tooling needs to re-generate tsconfig.json and react to changes. Here's an example for your package.json using nodemon (more on npm):

  "scripts": { 
      "dev": "nodemon -w tsconfig.js --exec \"run-s build:tsconfig dev:parcel\"",
      "build:tsconfig": "node tsconfig.js"
      "dev:parcel": "parcel src/index.html"
  }

Note that this example uses parcel, but it is tooling-agnostic. Use it in webpack or whatever you want!

I hope this helps you have a smoother time with your imports. If you have any questions, leave a comment below. Thanks for reading!

DEV Community: Zach