📔 Module Resolution

Parcel (v1.7.0 and above) supports multiple module resolution strategies out of the box so you don't have to deal with endless relative paths ../../.

Notable terms:

Absolute Paths

/foo will resolve foo relative to the project root.

~ Tilde Paths

~/foo will resolve foo relative to the nearest package root or, if not found, the project root.


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

This example aliases react to preact and some local custom module that is not in node_modules.

// package.json
  "name": "some-package",
  "devDependencies": {
    "parcel-bundler": "^1.7.0"
  "alias": {
    "react": "preact-compat",
    "react-dom": "preact-compat",
    "local-module": "./custom/modules"

Avoid using any special characters in your aliases as some may be used by Parcel and others by 3rd party tools or extensions. For example:

We advise being explicit when defining your aliases, so please specify file extensions, otherwise Parcel will need to guess. See JavaScript Named Exports for an example of this.

Other Conditions

JavaScript Named Exports

Alias mappings apply to many asset types and does not specifically support mapping of JavaScript named exports. If you wish to map JS named exports you can do this:

// package.json
  "name": "some-package",
  "alias": {
    "ipcRenderer": "./electron-ipc.js" // specify file extension

and re-export the named export within the aliased file:

// electron-ipc.js
module.exports = require("electron").ipcRenderer;

TypeScript ~ Resolution

TypeScript will need to know about your use of the ~ module resolution or alias mappings. Please refer to the TypeScript Module Resolution docs for further information.

// tsconfig.json
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "~*": ["./src/*"]

Monorepo Resolution

These are the advised usages with monorepos at this time:

Advised usage:

Unadvised usage:

If you're a monorepo user and would like to contribute to these recommendations, please provide example repos when opening issues to support the discussion.

Help us improve the docs

If something is missing or not entirely clear, please file an issue on the website repository or edit this page.