Using TypeScript `paths` and `baseUrl` with Parcel

#typescript #webdev #parcel

You might have heard about the new kid on the block of build tools for web - Parcel. It combines great scalable architecture with amazing zero-configuration developer experience while being lightning fast at the same time. You might have even thought about trying it out and maybe moving one of your TypeScript projects to it.

Unfortunately, if you were leveraging paths and baseUrl TypeScript Compiler options you will likely not have a great time moving - Parcel does not support these properties out of the box. This might be a huge problem for big codebases. You may also prefer TypeScript Compiler's way of handling absolute imports in your project to Parcel's ~ notation. This was the case for me so I decided to try out Parcel plugin ecosystem and create a Resolver Plugin of my own to solve this issue.

parcel-resolver-ts-base-url

The plugin I created is called parcel-resolver-ts-base-url (name parcel-resolver-tspaths was already taken by an outdated resolver). It has 0 dependencies (except for peer Parcel, of course), weighs barely over 1kb and uses memoization to speed up resolution processes.

You can install parcel-resolver-ts-base-url using npm or yarn:

npm i --save-dev parcel-resolver-ts-base-url
# or
yarn add -D parcel-resolver-ts-base-url

Then simply add parcel-resolver-ts-base-url to your .parcelrc:

{
  "extends": "@parcel/config-default",
  "resolvers": ["parcel-resolver-ts-base-url", "..."]
}

At the moment parcel doesn't provide a way I know of to specify tsconfig.json location. Therefore parcel-resolver-ts-base-url will use tsconfig.json from the project root.

From this point usage will be straightforward - just specify desired aliases in paths property and projects baseUrl and start building without ugly relative imports!

Known Issues and Limitations

At the moment this plugin is pretty raw and have not been tested in a large amount of use cases. So I figured it would be important to specify what to look for when using parcel-resolver-ts-base-url.

What will work:

baseUrl imports
paths aliases without and with a single wildcard
paths and baseUrl imports resolving to a npm package with main or module fields
Imports resolving to a folder with an index file
Imports resolving to files with /(c|m)?jsx?/ and /tsx?/ extensions

What will likely not work:

HMR is untested and might not work
Resource imports and imports with specified extensions are not supported
Aliases leading to node_modules will not be resolved as external dependencies
Custom tsconfig.json names and locations

If you are having other issues please consider leaving feedback at GitHub Issues - any feedback would be greatly appreciated. And if you are willing to contribute with solving one of the issues I would be very glad to receive a Pull Request with your solution.