#Features FAQ

#Style processing

#How to skip the preprocessing of Less / Sass files in bundleless mode?

Bundleless means that each source file is compiled and built separately, which can be understood as the process of code transformation of source files only. To skip the preprocessing of .less/.scss files, you need to:

1. Set source.entry to remove .less/.scss files from the entry.
2. Set output.copy to copy .less/.scss files to the output directory.
3. Set redirect.style.extension to false to disable the redirect behavior for the import path of .less/.scss files.

Below is an example of skipping the .scss file processing. All .scss files in src will be copied to the output directory and retained with consistent relative paths.

export default defineConfig({
  lib: [
    {
      // ...
      source: {
        entry: {
          index: ['./src/**', '!src/**/*.scss'],
        },
      },
      output: {
        copy: [{ from: '**/*.scss', context: path.join(__dirname, 'src') }],
      },
      redirect: {
        style: {
          extension: false,
        },
      },
    },
  ],
});

#Static assets processing

#How to skip the processing of static asset files in bundleless mode?

In bundleless mode, Rslib transforms the source static asset file into a JavaScript file and a static asset file that is emitted according to output.distPath by default, while preserving the import or require statements for static assets. To skip the above processing of static asset files, you need to:

1. Set source.entry to remove static asset files from the entry.
2. Set output.copy to copy static asset files to the output directory.
3. Set redirect.asset.extension to false to disable the redirect behavior for the import path of static asset files.

Below is an example of skipping the .png file processing. All .png files in src will be copied to the output directory and retained with consistent relative paths.

export default defineConfig({
  lib: [
    {
      // ...
      source: {
        entry: {
          index: ['./src/**', '!src/**/*.png'],
        },
      },
      output: {
        copy: [{ from: '**/*.png', context: path.join(__dirname, 'src') }],
      },
      redirect: {
        asset: {
          extension: false,
        },
      },
    },
  ],
});

#Code minification

#How to preserve all comments in the output files?

By default, Rslib uses SWC to remove comments. The corresponding SWC jsc.minify.format configuration is

{
    comments: 'some',
    preserveAnnotations: true,
}

This will only preserve some legal comments and annotations. If you want to preserve all comments, you can refer to the following configuration:

export default {
  lib: [
    // ...
  ],
  output: {
    minify: {
      jsOptions: {
        minimizerOptions: {
          format: {
            comments: 'all', // This will preserve all comments
          },
        },
      },
    },
  },
};

#How to compress the output size while preserving code readability?

Compressing code can reduce the output size and improve loading speed, but the compressed code is less readable and harder to debug. If you want to preserve code readability, you can keep variable names and disable compression to facilitate debugging. Refer to web-infra-dev/rsbuild#966.

export default {
  lib: [
    // ...
  ],
  output: {
    minify: {
      jsOptions: {
        minimizerOptions: {
          // preserve variable name and disable minify for easier debugging
          mangle: false,
          minify: false,
          compress: true,
        },
      },
    },
  },
};

#Declaration files generation

#How to avoid generating declaration files for certain files?

As shown below, Rslib ignores the files under the src/tests directory when emitting JavaScript outputs, but these files still generate corresponding declaration files.

export default {
  lib: [
    source: {
      entry: {
        index: ['src/**/*', '!src/tests/**/*'],
      }
    }
  ],
};

The entry set by source.entry can exclude some files that do not generate corresponding JavaScript outputs, but cannot exclude the generation of corresponding declaration files. This needs to be achieved by setting include and exclude in tsconfig.json, as shown below:

{
  "compilerOptions": {
    // ...
  },
  "include": ["src/**/*"],
  "exclude": ["src/tests/**/*"]
}

If you want to keep type prompts and checking for these files, but do not generate corresponding declaration files, you can inherit a basic tsconfig.json by extends and then override the include and exclude options as follows:

{
  "compilerOptions": {
    // ...
  },
  "include": ["src/**/*", "rslib.config.ts"]
}

{
  "extends": "./tsconfig.json",
  "compilerOptions": {
    // ...
  },
  "include": ["src/**/*"],
  "exclude": ["src/tests/**/*"]
}

The newly added tsconfig.build.json needs to be configured in the source.tsconfigPath option in rslib.config.ts:

export default {
  lib: [
    source: {
      entry: {
        index: ['src/**/*', '!src/tests/**/*'],
      }
    }
  ],
  source: {
    tsconfigPath: 'tsconfig.build.json',
  },
};

#How to additionally exclude specified dependencies when dts.bundle is true?

Rslib uses rsbuild-plugin-dts to generate declaration files, which supports configuration via output.externals for excluding certain dependencies from bundled declaration files.

For example, if @types/foo is only declared in devDependencies, according to the dependency handling logic of autoExternal, Rslib will try to bundle @types/foo into the declaration output files during the build. In this case, you can exclude @types/foo by configuring output.externals.

export default {
  lib: [
    // ...
  ],
  output: {
    externals: ['@types/foo'],
  },
};

In addition, if you only want to specify a few dependencies to be bundled into the declaration output files, you can configure dts.bundle.bundledPackages to achieve this. All other dependencies not in this configuration will be excluded.

#Rsbuild plugin

#Why does using modifyRsbuildConfig to modify the configuration does not take effect?

Rslib internally generates Rsbuild's environments configurations, and each configuration item in the lib array corresponds to a specific environment configuration.

modifyRsbuildConfig is a global hook that cannot be effective for configurations under a specific environment. It is usually used in Rslib to modify globally effective plugins, etc. Therefore, you need to use modifyEnvironmentConfig instead to modify the configuration of a specific environment.

Refer to Environment Plugin to learn how to develop an Environment Plugin.

#Miscellaneous

#How to preserve module variables such as __webpack_hash__ in the source code when generating outputs?

Rslib based on Rspack will transform module variables like __webpack_hash__, __webpack_nonce__, __webpack_public_path__, etc. to runtime code containing __webpack_require__ by default during build process. If you need to preserve these module variables in the outputs, you can configure source.define as follows:

1. Replace the module variables that need to be preserved in the source code with a unique name, such as __webpack_hash__ with WEBPACK_HASH, __webpack_nonce__ with WEBPACK_NONCE, __webpack_public_path__ with WEBPACK_PUBLIC_PATH, etc.

const isUpdateAvailable = () => lastCompilationHash !== __webpack_hash__; 
const isUpdateAvailable = () => lastCompilationHash !== WEBPACK_HASH; 

2. Add the module variables that need to be preserved in source.define. The key of the passed configuration object is the replaced variable name in the source code, and the value is the module variable that needs to be preserved in the outputs.

export default defineConfig({
  source: {
    define: {
      WEBPACK_HASH: '__webpack_hash__',
      WEBPACK_NONCE: '__webpack_nonce__',
      WEBPACK_PUBLIC_PATH: '__webpack_public_path__',
    },
  },
});