checks

• Type: object with the properties below
• Optional

Defined in: options/input-options.ts:708

Controls which warnings are emitted during the build process. Each option can be set to true (emit warning) or false (suppress warning).

cannotCallNamespace?

• Type: boolean
• Optional

Defined in: options/generated/checks-options.ts:109

Whether to emit warnings when a namespace is called as a function.

A module namespace object is an object and not a function. Calling it as a function will cause a runtime error.

main.js

import * as utils from './utils.js';

// This will trigger the warning
// because `utils` is a namespace object, not a function
utils();

utils.js

export function greet() {
  return 'Hello';
}

Default

true

circularDependency?

• Type: boolean
• Optional

Defined in: options/generated/checks-options.ts:13

Whether to emit warnings when detecting circular dependency.

Circular dependencies lead to a bigger bundle size and sometimes cause execution order issues and are better to avoid.

a.js

import { b } from './b.js';
export const a = 'a' + b;

b.js

import { a } from './a.js';
export const b = 'b' + a;

main.js

import { a } from './a.js';
console.log(a);

In this example, a.js imports from b.js, and b.js imports from a.js, creating a circular dependency.

Default

false

commonJsVariableInEsm?

• Type: boolean
• Optional

Defined in: options/generated/checks-options.ts:75

Whether to emit warnings when a CommonJS variable is used in an ES module.

CommonJS variables like module and exports are treated as global variables in ES modules and may not work as expected.

export const version = '1.0.0';

module.exports = { legacy: true }; // This triggers the warning

Default

true

configurationFieldConflict?

• Type: boolean
• Optional

Defined in: options/generated/checks-options.ts:117

Whether to emit warnings when a config value is overridden by another config value with a higher priority.

rolldown.config.js

export default {
  transform: {
    jsx: 'preserve',
  },
};

tsconfig.json

{
  "compilerOptions": {
    "jsx": "react"
  }
}

Default

true

couldNotCleanDirectory?

• Type: boolean
• Optional

Defined in: options/generated/checks-options.ts:133

Whether to emit warnings when Rolldown could not clean the output directory.

See output.cleanDir.

Default

true

duplicateShebang?

• Type: boolean
• Optional

Defined in: options/generated/checks-options.ts:149

Whether to emit warnings when both the code and postBanner contain shebang

Having multiple shebangs in a file is a syntax error.

Default

true

emptyImportMeta?

• Type: boolean
• Optional

Defined in: options/generated/checks-options.ts:93

Whether to emit warnings when import.meta is not supported with the output format and is replaced with an empty object ({}).

See import.meta in Non-ESM Output Formats page for more details.

Default

true

eval?

• Type: boolean
• Optional

Defined in: options/generated/checks-options.ts:21

Whether to emit warnings when detecting uses of direct evals.

See Avoiding Direct eval in Troubleshooting page for more details.

Default

true

filenameConflict?

• Type: boolean
• Optional

Defined in: options/generated/checks-options.ts:65

Whether to emit warnings when files generated have the same name with different contents.

For example, this warning happens with the following config:

rolldown.config.js

export default {
  input: ['src/entry1.js', 'src/entry2.js'],
  output: {
    // Both entries will try to use the same filename
    entryFileNames: 'bundle.js',
  },
};

Default

true

importIsUndefined?

• Type: boolean
• Optional

Defined in: options/generated/checks-options.ts:85

Whether to emit warnings when an imported variable is not exported.

If the code is importing a variable that is not exported by the imported module, the value will always be undefined. This might be a mistake in the code.

main.js

import * as utils from './utils.js'; // 'nonExistent' is not exported
console.log(utils.nonExistent); // Always undefined

utils.js

export const helper = () => 'help';

Default

true

ineffectiveDynamicImport?

• Type: boolean
• Optional

Defined in: options/generated/checks-options.ts:161

Whether to emit warnings when a module is dynamically imported but also statically imported, making the dynamic import ineffective for code splitting.

Default

true

missingGlobalName?

• Type: boolean
• Optional

Defined in: options/generated/checks-options.ts:29

Whether to emit warnings when the output.globals option is missing when needed.

See output.globals.

Default

true

missingNameOptionForIifeExport?

• Type: boolean
• Optional

Defined in: options/generated/checks-options.ts:37

Whether to emit warnings when the output.name option is missing when needed.

See output.name.

Default

true

mixedExports?

• Type: boolean
• Optional

Defined in: options/generated/checks-options.ts:45

Whether to emit warnings when the way to export values is ambiguous.

See output.exports.

Default

true

pluginTimings?

• Type: boolean
• Optional

Defined in: options/generated/checks-options.ts:141

Whether to emit warnings when plugins take significant time during the build process.

When enabled, Rolldown measures time spent in each plugin hook. If plugins significantly impact build performance, a warning is emitted with a breakdown of plugin timings.

How it works:

1. Minimum build time: To avoid noisy warnings for fast builds, the warning is only triggered if Rolldown's internal build time (Rust side) exceeds 3 seconds.

2. Detection threshold: A warning is triggered when plugin time (total build time minus link stage time) exceeds 100x the link stage time. This threshold was determined by studying plugin impact on real-world projects.

3. Identifying plugins: When the threshold is exceeded, Rolldown reports up to 5 plugins that take longer than the average plugin time, sorted by duration. Each plugin shows its percentage of total plugin time. Only plugins with total duration of at least 1 second are included in the report.

WARNING

For hooks using this.resolve() or this.load(), the reported time includes waiting for other plugins, which may overestimate that plugin's actual cost.

Additionally, since plugin hooks execute concurrently, the statistics represent accumulated time rather than wall-clock time. The measured duration also includes Rust-side processing overhead, Tokio async scheduling overhead, NAPI data conversion overhead, and JavaScript event loop overhead.

Default

true

preferBuiltinFeature?

• Type: boolean
• Optional

Defined in: options/generated/checks-options.ts:125

Whether to emit warnings when a plugin that is covered by a built-in feature is used.

Using built-in features is generally more performant than using plugins.

Default

true

toleratedTransform?

• Type: boolean
• Optional

Defined in: options/generated/checks-options.ts:99

Whether to emit warnings when detecting tolerated transform.

Default

true

unresolvedEntry?

• Type: boolean
• Optional

Defined in: options/generated/checks-options.ts:51

Whether to emit warnings when an entrypoint cannot be resolved.

Default

true

unresolvedImport?

• Type: boolean
• Optional

Defined in: options/generated/checks-options.ts:57

Whether to emit warnings when an import cannot be resolved.

Default

true

unsupportedTsconfigOption?

• Type: boolean
• Optional

Defined in: options/generated/checks-options.ts:155

Whether to emit warnings when a tsconfig option or combination of options is not supported.

Default

true