Path Aliases#

Path aliases allow developers to define aliases for modules, making it easier to reference them in code. This can be useful when you want to use a short, easy-to-remember name for a module instead of a long, complex path.

For example, if you frequently reference the src/common/request.ts module in your project, you can define an alias for it as @request and then use import request from '@request' in your code instead of writing the full relative path every time. This also allows you to move the module to a different location without needing to update all the import statements in your code.

import request from '@request'; // resolve to `src/common/request.ts`

In Rsbuild, there are two ways to set up path aliases:

• Use the paths configuration in tsconfig.json.
• Use the resolve.alias configuration.

paths in tsconfig.json#

You can configure aliases through the paths configuration in tsconfig.json, which is the recommended approach in TypeScript projects as it also resolves the TS type issues related to path aliases.

For example:

{
  "compilerOptions": {
    "paths": {
      "@common/*": ["./src/common/*"]
    }
  }
}

After configuring, if you reference @common/Foo.tsx in your code, it will be mapped to the <project>/src/common/Foo.tsx path.

jsconfig.json#

In non-TypeScript projects, if you need to set path aliases through the paths field in jsconfig.json, you can use the source.tsconfigPath option to set it.

After adding the following configuration, Rsbuild will recognize the paths field in jsconfig.json.

export default {
  source: {
    tsconfigPath: './jsconfig.json',
  },
};

resolve.alias Configuration#

Rsbuild provides the resolve.alias configuration option, which corresponds to the webpack/Rspack native resolve.alias configuration. You can configure this option using an object or a function.

Use Cases#

Since the paths configuration in tsconfig.json is written in a static JSON file, it lacks dynamism.

The resolve.alias configuration can address this limitation by allowing you to dynamically set the resolve.alias using JavaScript code, such as based on environment variables.

Object Usage#

You can configure resolve.alias using an object, where the relative paths will be automatically resolved to absolute paths.

For example:

export default {
  resolve: {
    alias: {
      '@common': './src/common',
    },
  },
};

After configuring, if you reference @common/Foo.tsx in your code, it will be mapped to the <project>/src/common/Foo.tsx path.

Function Usage#

You can also configure resolve.alias as a function, which receives the built-in alias object and allows you to modify it.

For example:

export default {
  resolve: {
    alias: (alias) => {
      alias['@common'] = './src/common';
      return alias;
    },
  },
};

Priority#

The paths configuration in tsconfig.json takes precedence over the resolve.alias configuration. When a path matches the rules defined in both paths and resolve.alias, the value defined in paths will be used.

You can adjust the priority of these two options using resolve.aliasStrategy.