#lib.experiments

Used to enable some Rslib experimental features.

#experiments.advancedEsm

• Type: boolean
• Default: true

Controls whether to enable Rspack experimental ESM output. When enabled, it emits ESM output that is high-quality, more friendly to static analysis, and supports code splitting.

If you need to disable this feature, you can set it to false:

export default {
  lib: [
    {
      format: 'esm',
      bundle: true,
      experiments: {
        advancedEsm: false,
      },
    },
  ],
};

#Version history

#experiments.exe

Use Node.js Single Executable Application to package the generated JavaScript output into an executable file.

This feature allows you to conveniently distribute a Node.js application to systems without Node.js installed.

• Type:

type SeaOptions = {
  disableExperimentalSEAWarning?: boolean;
  useSnapshot?: boolean;
  useCodeCache?: boolean;
  execArgv?: string[];
  execArgvExtension?: 'none' | 'env' | 'cli';
  assets?: Record<string, string>;
};

type ExeOptions =
  | boolean
  | {
      fileName?: string;
      outputPath?: string;
      targets?: Array<
        | string
        | {
            platform?: 'darwin' | 'linux' | 'win32';
            arch?: 'x64' | 'arm64';
            nodeVersion?: string;
          }
      >;
      seaOptions?: SeaOptions;
    };

• Default: false

#Conditions and limits

To enable experiments.exe, make sure that:

• format is 'esm' or 'cjs'
• output.target is 'node'
• bundle is true
• There is only one entry in source.entry

After enabling experiments.exe, Rslib will also:

• Disable code splitting
• Ignore autoExternal, output.externals, externalHelpers, and related options, and bundle all modules directly into the executable

#Boolean type

You can set experiments.exe to true to enable executable generation with the default behavior.

In this mode, Rslib uses the current process.execPath as the executable template and outputs the generated executable to the current JavaScript output directory.

This means the generated executable uses:

• The current host platform (process.platform)
• The current host arch (process.arch)
• The current Node.js version (process.version)

export default {
  lib: [
    {
      experiments: {
        exe: true,
      },
    },
  ],
};

If you want to disable this feature, you can set experiments.exe to false or leave it unspecified.

#Object type

If you want to customize executable generation, you can set experiments.exe to an object.

#experiments.exe.fileName

• Type: string

Specify the executable file name.

By default, Rslib uses the entry JavaScript file name as the default file name. For win32 targets, Rslib appends the .exe suffix automatically.

When multiple targets are configured, Rslib appends -<platform>-<arch>-<nodeVersion> to avoid file name conflicts.

export default {
  lib: [
    {
      experiments: {
        exe: {
          fileName: 'hello',
        },
      },
    },
  ],
};

#experiments.exe.outputPath

• Type: string

Specify the output directory of the executable file.

By default, Rslib outputs the executable to the current JavaScript output directory.

export default {
  lib: [
    {
      experiments: {
        exe: {
          outputPath: './build',
        },
      },
    },
  ],
};

#experiments.exe.targets

• Type:

type ExeTargets = Array<string | ExeTarget>;

type ExeTarget = {
  platform?: 'darwin' | 'linux' | 'win32';
  arch?: 'x64' | 'arm64';
  nodeVersion?: string;
};

Specify the list of executable targets to generate. Each item supports one of the following types:

• String type: a custom Node.js executable path. Rslib uses this binary as the executable template, and uses a host-runnable Node.js binary with the same version for --build-sea.

Here is an example that uses a custom Node.js binary path:

export default {
  lib: [
    {
      experiments: {
        exe: {
          targets: ['./custom-node/bin/node'],
        },
      },
    },
  ],
};

• Object type: declares the target platform, arch, and nodeVersion. nodeVersion accepts both '25.9.0' and 'v25.9.0'. Rslib resolves or downloads the matching official Node.js executable automatically. Omitted fields fall back to the current host environment. If targets is not specified, or is an empty array, it falls back to the same default behavior as the boolean form.

Here is an example that generates executables for multiple platforms in a single build:

export default {
  lib: [
    {
      experiments: {
        exe: {
          targets: [
            {
              platform: 'linux',
              arch: 'x64',
            },
            {
              platform: 'darwin',
              arch: 'arm64',
            },
            {
              platform: 'win32',
              arch: 'x64',
            },
          ],
        },
      },
    },
  ],
};

#experiments.exe.seaOptions

• Type:

type SeaOptions = {
  disableExperimentalSEAWarning?: boolean;
  useSnapshot?: boolean;
  useCodeCache?: boolean;
  execArgv?: string[];
  execArgvExtension?: 'none' | 'env' | 'cli';
  assets?: Record<string, string>;
};

• Default:

const defaultSeaOptions = {
  disableExperimentalSEAWarning: true,
  useSnapshot: false,
  useCodeCache: false,
  execArgv: undefined,
  execArgvExtension: 'env',
  assets: undefined,
};

seaOptions is passed directly to Node.js SEA configuration.

If a target differs from the current host platform or architecture, Rslib automatically disables useSnapshot and useCodeCache for that target to keep cross-platform builds compatible.

In addition, useSnapshot cannot be used together with format: 'esm'.

For the complete behavior, see the Node.js SEA documentation.

#Run the executable

• On systems other than Windows:

$ ./hello world
Hello, world!

• On Windows:

$ .\hello.exe world
Hello, world!

#Version history