> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# lib.redirect

:::info

`redirect` is the unique configuration for [bundleless mode](/guide/basic/output-structure.md#bundle--bundleless). It will not take effect in bundle mode where all output files are bundled into a single file, eliminating the need for import path redirection.

:::

- **Type:**

```ts
type JsRedirect = {
  path?: boolean;
  extension?: boolean;
};

type StyleRedirect = {
  path?: boolean;
  extension?: boolean;
};

type AssetRedirect = {
  path?: boolean;
  extension?: boolean;
};

type DtsRedirect = {
  path?: boolean;
  extension?: boolean;
};

type Redirect = {
  js?: JsRedirect;
  style?: StyleRedirect;
  asset?: AssetRedirect;
  dts?: DtsRedirect;
};
```

- **Default:**

```ts
const defaultRedirect = {
  js: {
    path: true,
    extension: true,
  },
  style: {
    path: true,
    extension: true,
  },
  asset: {
    path: true,
    extension: true,
  },
  dts: {
    path: true,
    extension: true,
  },
};
```

- **Top-level config:** Supported

Configure the redirect for import paths in output files.

In bundleless mode, there are often needs such as using aliases or automatically appending suffixes for ESM outputs. The `redirect` configuration is designed to address these issues.

## redirect.js

Controls the redirect of the import paths of output JavaScript files.

- **Example:**

By default, when set `compilerOptions.paths` to `{ "@/*": ["src/*"] }` in `tsconfig.json`, the import path for the JavaScript output file will be redirected to the correct relative path and the corresponding file extension will be added:

```ts
import { foo } from '@/foo'; // source code of './src/bar.ts' ↓
import { foo } from './foo.mjs'; // expected output of './dist/bar.mjs'

import { foo } from '@/foo'; // source code of './src/utils/index.ts' ↓
import { foo } from '../foo.mjs'; // expected output of './dist/utils/index.mjs'
```

:::warning

When [output.externals](/config/rsbuild/output.md#outputexternals) is configured and a request is matched, neither `redirect.js.path` nor `redirect.js.extension` will take effect, and the final redirected request path will be entirely controlled by [output.externals](/config/rsbuild/output.md#outputexternals).

:::

### redirect.js.path

Whether to automatically redirect the import paths of JavaScript output files.

- **Type:** `boolean`
- **Default:** `true`

When set to `true`, [resolve.alias](/config/rsbuild/resolve.md#resolvealias) and [resolve.aliasStrategy](/config/rsbuild/resolve.md#resolvealiasstrategy) will take effect in the output file, and the import path of the output file will be redirected. For TypeScript projects, just configure [compilerOptions.paths](https://typescriptlang.org/tsconfig#paths) in the `tsconfig.json` file.

When set to `false`, the import path will not be effected by [resolve.alias](/config/rsbuild/resolve.md#resolvealias), [resolve.aliasStrategy](/config/rsbuild/resolve.md#resolvealiasstrategy) and `tsconfig.json`.

- **Example:**

When set `compilerOptions.paths` to `{ "@/*": ["src/*"] }` in `tsconfig.json`, the import path for the JavaScript output file will be redirected to the correct relative path:

```ts
import { foo } from '@/foo'; // source code of './src/bar.ts' ↓
import { foo } from './foo'; // expected output of './dist/bar.js'

import { foo } from '@/foo'; // source code of './src/utils/index.ts' ↓
import { foo } from '../foo'; // expected output './dist/utils/index.js'
```

### redirect.js.extension

Whether to automatically redirect the file extension of import paths based on the JavaScript output files.

- **Type:** `boolean`
- **Default:** `true`

When set to `true`, the file extension of import paths in JavaScript output files that can be resolved correctly will be automatically completed or replaced.

When set to `false`, import paths will retain their original file extensions.

:::note
The extension of the JavaScript output file is related to the [autoExtension](/config/lib/auto-extension.md#libautoextension) configuration.
:::

- **Example:**

For ESM outputs running in Node.js, the full extension to the module import path must be specified to load correctly. Rslib will automatically add corresponding file extensions based on the actual output JavaScript file.

```ts
import { foo } from './foo'; // source code of './src/bar.ts' ↓
import { foo } from './foo.mjs'; // expected output of './dist/bar.mjs'

import { foo } from './foo.ts'; // source code of './src/utils/index.ts' ↓
import { foo } from './foo.mjs'; // expected output './dist/utils/index.mjs'
```

## redirect.style

Controls the redirect of the import paths of output style files.

- **Example:**

By default, when `compilerOptions.paths` is set to `{ "@/*": ["src/*"] }` in `tsconfig.json`, the import paths of style output files will be redirected to the correct relative paths. Additionally, when importing [CSS Modules](/config/rsbuild/output.md#outputcssmodules), the file extension will be rewritten to the corresponding JavaScript output file extension.

```ts
import '@/foo.css'; // source code of './src/bar.ts' ↓
import './foo.css'; // expected output of './dist/bar.js'

import styles from '@/foo.module.less'; // source code of './src/baz.ts' ↓
import styles from './foo.module.mjs'; // expected output of './dist/baz.mjs'
```

### redirect.style.path

Whether to automatically redirect the import paths of style output files.

- **Type:** `boolean`
- **Default:** `true`

When set to `true`, the relevant redirect rules are the same as [redirect.js.path](/config/lib/redirect.md#redirectjspath).

When set to `false`, the original import path will remain unchanged.

- **Example:**

When set `compilerOptions.paths` to `{ "@/*": ["src/*"] }` in `tsconfig.json`, the import path for the style output file will be redirected to the correct relative path.

When importing normal style files:

```ts
import '@/foo.css'; // source code of './src/bar.ts' ↓
import './foo.css'; // expected output of './dist/bar.js'

import '@/foo.css'; // source code of './src/utils/index.ts' ↓
import '../foo.css'; // expected output of './dist/utils/index.js'
```

When importing [CSS Modules](/config/rsbuild/output.md#outputcssmodules) files:

```ts
import styles from '@/foo.css'; // source code of './src/bar.ts' ↓
import styles from './foo.css'; // expected output of './dist/bar.js'

import styles from '@/foo.css'; // source code of './src/utils/index.ts' ↓
import styles from '../foo.css'; // expected output of './dist/utils/index.js'
```

### redirect.style.extension

Whether to automatically redirect the file extension of import paths based on the style output files.

- **Type:** `boolean`
- **Default:** `true`

When set to `true`:

- When importing a normal style file, the path will be redirected to `.css`.
- When importing [CSS Modules](/config/rsbuild/output.md#outputcssmodules), the file extension will be redirected to the corresponding JavaScript output file extension.

When set to `false`, the file extension will remain unchanged from the original import path.

- **Example:**

When importing from a `.less` file:

```ts
import './index.less'; // source code ↓
import './index.css'; // expected output

import styles from './index.module.less'; // source code ↓
import styles from './index.module.mjs'; // expected output
```

## redirect.asset

Controls the redirect of the import paths of output asset files.

- **Example:**

By default, when `compilerOptions.paths` is set to `{ "@/*": ["src/*"] }` in `tsconfig.json`, the import paths of asset files will be redirected to the correct relative paths, and the file extensions will be rewritten to the corresponding JavaScript output file extensions.

```ts
import url from '@/assets/logo.svg'; // source code of './src/foo.ts' ↓
import url from './assets/logo.mjs'; // expected output of './dist/foo.mjs'
```

### redirect.asset.path

Whether to automatically redirect the import paths of asset output files.

- **Type:** `boolean`
- **Default:** `true`

When set to `true`, the relevant redirect rules are the same as [redirect.js.path](/config/lib/redirect.md#redirectjspath).

When set to `false`, the original import path will remain unchanged.

- **Example:**

When set `compilerOptions.paths` to `{ "@/*": ["src/*"] }` in `tsconfig.json`, the import path for the asset file will be redirected to the correct relative path:

```ts
import url from '@/assets/logo.svg'; // source code of './src/foo.ts' ↓
import url from './assets/logo.svg'; // expected output of './dist/foo.js'
```

### redirect.asset.extension

Whether to automatically redirect the file extension of import paths based on the asset output files.

- **Type:** `boolean`
- **Default:** `true`

When set to `true`, the file extension of imported asset files will be redirected to the corresponding JavaScript output file extension.

When set to `false`, the file extension will remain unchanged from the original import path.

- **Example:**

```ts
import url from './assets/logo.svg'; // source code of './src/foo.ts' ↓
import url from './assets/logo.mjs'; // expected output of './dist/foo.mjs'
```

::: note

The way to import static assets in a JavaScript file and the corresponding output structure, please see [Static assets](/guide/advanced/static-assets.md#import-assets-in-javascript-file).

:::

## redirect.dts

Controls the redirect of the import paths of output TypeScript declaration files.

- **Example:**

By default, when `compilerOptions.paths` is set to `{ "@/*": ["src/*"] }` in `tsconfig.json`, the import path in the declaration output file will be redirected to the correct relative path:

```ts
import { foo } from '@/foo'; // source code of './src/bar.ts' ↓
import { foo } from './foo'; // expected output of './dist/bar.d.ts'
```

### redirect.dts.path

Whether to automatically redirect the import paths of TypeScript declaration output files.

- **Type:** `boolean`
- **Default:** `true`

When set to `true`, Rslib will redirect the import path in the declaration output file to the corresponding relative path based on the [compilerOptions.paths](https://typescriptlang.org/tsconfig#paths) configured in `tsconfig.json`.

When set to `false`, the original import path will remain unchanged.

- **Example:**

When `compilerOptions.paths` is set to `{ "@/*": ["src/*"] }` in `tsconfig.json`, the import path in the declaration output file will be redirected to the correct relative path:

```ts
import { foo } from '@/foo'; // source code of './src/bar.ts' ↓
import { foo } from './foo'; // expected output of './dist/bar.d.ts'

import { foo } from '@/foo'; // source code of './src/utils/index.ts' ↓
import { foo } from '../foo'; // expected output './dist/utils/index.d.ts'
```

### redirect.dts.extension

Whether to automatically redirect the file extension of import paths based on the TypeScript declaration output files.

- **Type:** `boolean`
- **Default:** `true`

When set to `true`, the file extension of the import path in the declaration file will be automatically completed or replaced with the corresponding JavaScript file extension that can be resolved to the corresponding declaration file.

When set to `false`, import paths will retain their original file extensions.

:::note
The extension of the TypeScript declaration file is related to the [dts.autoExtension](/config/lib/dts.md#dtsautoextension) configuration.
:::

- **Example:**

When loading a module with `moduleResolution: 'nodenext'`, the import path needs to include the full file extension. Rslib will automatically add the corresponding file extension based on the actual JavaScript output file.

```ts
import { foo } from './foo'; // source code of './src/bar.ts' ↓
import { foo } from './foo.mjs'; // expected output of './dist/bar.d.mts'

import { foo } from './foo.ts'; // source code of './src/bar.ts' ↓
import { foo } from './foo.mjs'; // expected output of './dist/bar.d.mts'
```

#### Notes

This option also applies to declaration import paths rewritten through [`paths`](https://typescriptlang.org/tsconfig#paths) or [`dts.alias`](/config/lib/dts.md#dtsalias). Note the following cases:

- Rslib probes for an `index` entry under the configured path, but does not use the `types` field, the `types` condition name in `exports`, or `typesVersions` from the directory's `package.json` to locate a declaration entry. If an entry must be resolved using this package metadata, point the configured path directly to that entry. For example, when `vendor/foo/package.json` contains `"types": "./typings/main.d.ts"`:

  ```diff title="rslib.config.ts"
   dts: {
     alias: {
  -    foo: './vendor/foo',
  +    foo: './vendor/foo/typings/main',
     },
   },
  ```

- If the CommonJS declaration referenced by a configured path originally uses `export =`, preserve that export form instead of converting it to `export default`. Otherwise, when the module is resolved with NodeNext from an ESM declaration, CommonJS default interop may combine with the explicit default export and move the original namespace members one level under `default`. For example:

  ```diff title="foo/index.d.ts"
   declare function Foo(): void;
   declare namespace Foo {
     interface Options {}
   }

  -export { Foo as default };
  +export = Foo;
  ```

Bare package imports that do not match `paths` or `dts.alias` are not rewritten and continue to use TypeScript's package resolution.