source.alias#

• Type:

type Alias = Record<string, string | false | (string | false)[]> | Function;

• Default:

const defaultAlias = {
  '@swc/helpers': path.dirname(require.resolve('@swc/helpers/package.json')),
};

Create aliases to import or require certain modules, same as the resolve.alias config of Rspack.

Object Type#

The alias can be an Object, and the relative path will be automatically converted to absolute path.

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

With above configuration, if @common/Foo.tsx is import in the code, it will be mapped to the <project>/src/common/Foo.tsx path.

Function Type#

The alias can be a function, it will accept the previous alias object, and you can modify it.

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

If you need to remove the built-in @swc/helpers alias, you can delete it in the function:

export default {
  source: {
    alias: (alias) => {
      delete alias['@swc/helpers'];
    },
  },
};

You can also return a new object as the final result in the function, which will replace the preset alias object.

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

Set by environment#

When you build for multiple environments, you can set different alias for each environment:

For example, set different alias for web and node environments:

export default {
  environments: {
    web: {
      source: {
        alias: {
          '@common': './src/web/common',
        },
      },
      output: {
        target: 'web',
      },
    },
    node: {
      source: {
        alias: {
          '@common': './src/node/common',
        },
      },
      output: {
        target: 'node',
      },
    },
  },
};

Exact Matching#

By default, source.alias will automatically match sub-paths, for example, with the following configuration:

import path from 'node:path';

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

It will match as follows:

import a from '@common'; // resolved to `./src/common`
import b from '@common/util'; // resolved to `./src/common/util`

You can add the $ symbol to enable exact matching, which will not automatically match sub-paths.

import path from 'node:path';

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

It will match as follows:

import a from '@common'; // resolved to `./src/common`
import b from '@common/util'; // remains as `@common/util`

Handling npm packages#

You can use alias to resolve an npm package to a specific directory.

For example, if multiple versions of the react are installed in the project, you can alias react to the version installed in the root node_modules directory to avoid bundling multiple copies of the React code.

import path from 'node:path';

export default {
  source: {
    alias: {
      react: path.resolve(__dirname, './node_modules/react'),
    },
  },
};

When using alias to handle npm packages, please be aware of whether different major versions of the package are being used in the project.

For example, if a module or npm dependency in your project uses the React 18 API, and you alias React to version 17, the module will not be able to reference the React 18 API, resulting in code exceptions.