指令

JavaScript 有一个称为 directive 的特性，用于对代码的一部分进行注释。

Rolldown 可能无法保留与指令相关的语义，以下是在处理指令时的策略。

"use strict"

"use strict" 指令用于告知 JavaScript 引擎启用严格模式。由于保留顶层 "use strict" 指令的语义较为复杂，且会需要更大的输出体积，Rolldown 可能不会保留它们。

由于 ES 模块始终处于严格模式，Rolldown 不会为 output.format: 'es' 输出任何 "use strict" 指令。顺带一提，这意味着对于 ES 模块格式的输出，原本不处于严格模式的代码会被强制置于严格模式。

你可以使用 output.strict 选项来控制 "use strict" 指令的输出：

• true - 始终在输出顶部发出 "use strict"（由于 ESM 格式始终是严格模式，因此不适用于 ESM 格式）。
• false - 从不在输出中发出 "use strict"。
• 'auto'（默认） - 遵循源代码中的 "use strict" 指令。

import { defineConfig } from 'rolldown';

export default defineConfig({
  output: {
    format: 'cjs',
    strict: true,
  },
});

当 output.format 不是 'es' 且 output.strict 为 'auto' 时，Rolldown 会在以下任一情况下输出 "use strict" 指令：

• 该指令不在顶层作用域内，也不在严格模式作用域内 (REPL)
• 该指令位于顶层作用域中，且该模块是入口模块 (REPL)
• 该指令位于顶层作用域中，并且启用了 output.preserveModules (REPL)

其他指令

ECMAScript 规范允许实现定义额外的指令。由于这些额外的指令不属于该规范，Rolldown 并不知道它们的语义。Rolldown 假定它们遵循与 "use strict" 类似的语义。但出于与上文相同的原因，Rolldown 可能不会保留顶层指令。

Rolldown 会在以下任一情况下输出该指令：

• 该指令不在顶层作用域内 (REPL)
• 该指令位于顶层作用域中，且该模块是入口模块 (REPL)
• 该指令位于顶层作用域中，并且启用了 output.preserveModules (REPL)

如果你想为所有文件追加自定义指令，可以使用 output.banner 选项：

import { defineConfig } from 'rolldown';

export default defineConfig({
  output: {
    banner: "'use client';",
  },
});