rollup 插件开发 - 输出钩子

rollup 插件开发 - 输出钩子

outputOptions

(outputOptions: OutputOptions) => OutputOptions \| null

替换或操作传递给 bundle.generate() 或 bundle.write() 的输出选项对象。返回 null 不会替换任何内容。如果我们只需要读取输出选项，则建议使用 renderStart 钩子，因为此钩子在考虑所有 outputOptions 钩子的转换后可以访问输出选项。

主要用于设置参数配置。

renderStart

(outputOptions: OutputOptions, inputOptions: InputOptions) => void

每次调用 bundle.generate() 或 bundle.write() 时最初调用。要在生成完成时得到通知，请使用 generateBundle 和 renderError 钩子。这是建议使用的钩子，当我们需要访问传递给 bundle.generate() 或 bundle.write() 的输出选项时，它会考虑所有 outputOptions 钩子的转换，并且还包含未设置选项的正确默认值。它还接收传递给 rollup.rollup() 的输入选项，以便可以将可用作输出插件的插件（即仅使用 generate 阶段钩子的插件）访问它们。

主要用于读取参数配置。

renderDynamicImport

动态导入就是使用 import() 方法导入的模块。

(options: {
    customResolution: string | null;
    format: string;
    moduleId: string;
    targetModuleId: string | null;
}) => { left: string; right: string } | null;

format 是呈现的输出格式， moduleId 是执行动态导入的模块的 ID。如果导入可以解析为内部或外部 ID，则 targetModuleId 将设置为此 ID，否则将为 null。如果动态导入包含由 resolveDynamicImport 钩子解析为替换字符串的非字符串表达式，则 customResolution 将包含该字符串。

此钩子通过提供导入表达式参数左侧（import(）和右侧（)）的代码替换（中间模块的地址信息不变），提供了对动态导入如何呈现的细粒度控制。返回null将推迟到此类型的其他钩子，最终呈现特定于格式的默认值。

以下代码将使用自定义处理程序替换所有动态导入，添加 import.meta.url 作为第二个参数，以允许处理程序正确解析相对导入

function dynamicImportPolyfillPlugin() {
    return {
        name: 'dynamic-import-polyfill',
        renderDynamicImport() {
            return {
                left: 'dynamicImportPolyfill(',
                right: ', import.meta.url)'
            };
        }
    };
}

// 输入
import('./lib.js');

// 输出
dynamicImportPolyfill('./lib.js', import.meta.url);

resolveFileUrl

(options: {
    chunkId: string;
    fileName: string;
    format: InternalModuleFormat;
    moduleId: string;
    referenceId: string;
    relativePath: string;
}) => string | NullValue;

允许自定义 Rollup 如何解析由插件通过 this.emitFile 产出的文件的 URL。

resolveImportMeta

(property: string \| null, {chunkId: string, moduleId: string, format: string}) => string \| null

自定义 Rollup 如何处理 import.meta 和 import.meta.someProperty，特别是 import.meta.url。在 ES 模块中，import.meta 是一个对象，import.meta.url 包含当前模块的 URL，例如在浏览器中为http://server.net/bundle.js，在 Node 中为file:///path/to/bundle.js

当解析出的代码中存在 import.meta<.someProperty>时就会触发这个钩子，并传入属性的名称或者如果直接访问 import.meta 则为 null。

默认情况下，对于除 ES 模块以外的格式，Rollup 将 import.meta.url 替换为尝试匹配此行为的代码，返回当前块的动态 URL。请注意，除 CommonJS 和 UMD 之外的所有格式都假定它们在浏览器环境中运行，其中URL和document可用。

以下代码将使用原始模块相对路径到当前工作目录的解析 import.meta.url，并在运行时再次将此路径解析为当前文档的基本 URL：

function importMetaUrlCurrentModulePlugin() {
    return {
        name: 'import-meta-url-current-module',
        resolveImportMeta(property, { moduleId }) {
            if (property === 'url') {
                return `new URL('${path.relative(
                    process.cwd(),
                    moduleId
                )}', document.baseURI).href`;
            }
            return null;
        }
    };
}

// 将 import.meta.url 解析成 new URL('index.js', document.baseURI).href

banner

string \| ((chunk: ChunkInfo) => string)

文件顶部注释。如果设置了 output.banner， 那么 banner 钩子函数里定义的注释会处于 output.banner 之下。

比如：

output: {
    plugins: [
        {
          banner() {
            return '// plugin banner';
          },
          // 也可以这样用：
          banner: '// plugin banner'
        },
    ],
    banner: '// this is a banner',
}

// 输出
// this is a banner
// plugin banner
// ....

footer

string \| ((chunk: ChunkInfo) => string)

文件底部注释。如果设置了 output.footer， 那么 footer 钩子函数里定义的注释会处于 output.footer 之下。

比如：

output: {
    plugins: [
        {
          footer() {
            return '// plugin footer';
          },
          // 也可以这样用：
          footer: '// plugin footer'
        },
    ],
    footer: '// this is a footer',
}

// 输出
// ...
// this is a footer
// plugin footer

intro

string \| ((chunk: ChunkInfo) => string\| Promise<string>)

在文件顶部添加代码（如果设置了 banner，那么会出现在 banner 下面），除了在特定格式中代码不同外，该钩子函数功能和 banner、footer 类似。如果设置了 output.intro，那么 intro 钩子函数里定义的代码会处于 output.intro 之下。

output: {
    plugins: [
        {
          // 有以下三种写法
          async intro() {
            return await resolveIntro();
          },
          // 或者
          intro() {
            return 'plugin intro';
          },
          // 或者
          intro: 'plugin intro'
        },
    ],
    // 有以下三种写法
    intro: 'output intro',
    // 或者
    intro() { return 'output intro' },
    // 或者
    async intro() {
        return await resolveIntro();
    },
}

// 输出
// output intro
// plugin intro
// ...

outro

string \| ((chunk: ChunkInfo) => string\| Promise<string>)

在文件底部添加代码（如果设置了 footer，那么会出现在 footer 上面），除了在特定格式中代码不同外，用法与 outro 类似。如果设置了 output.outro，那么 outro 钩子函数里定义的代码会处于 output.outro 之下。

output: {
    plugins: [
        {
          // 有以下三种写法
          async outro() {
            return await resolveOutro();
          },
          // 或者
          outro() {
            return 'plugin outro';
          },
          // 或者
          outro: 'plugin outro'
        },
    ],
    // 有以下三种写法
    outro: 'output outro',
    // 或者
    outro() { return 'output outro' },
    // 或者
    async outro() {
        return await resolveOutro();
    },
}

// 输出
// output intro
// plugin intro
// ...

renderChunk

(
    code: string,
    chunk: RenderedChunk,
    options: NormalizedOutputOptions,
    meta: { chunks: Record<string, RenderedChunk> }
) => { code: string; map?: SourceMapInput } | string | null;

可以用于转换单个块。对于每个 Rollup 输出块文件都会调用此函数。返回 null 将不应用任何转换。

augmentChunkHash

(chunkInfo: ChunkInfo) => string

可用于增加单个块的哈希值。为每个 Rollup 输出块调用。返回 falsy 值不会修改哈希值。Truthy 值将传递给 hash.update。chunkInfo 是 generateBundle 中的版本的简化版本，不包括 code 和 map，并在文件名中使用哈希的占位符。

generateBundle

(options: OutputOptions, bundle: { [fileName: string]: OutputAsset \| OutputChunk }, isWrite: boolean) => void

interface OutputAsset {
    fileName: string;
    name?: string;
    needsCodeReference: boolean;
    source: string | Uint8Array;
    type: 'asset';
}

interface OutputChunk {
    code: string;
    dynamicImports: string[];
    exports: string[];
    facadeModuleId: string | null;
    fileName: string;
    implicitlyLoadedBefore: string[];
    imports: string[];
    importedBindings: { [imported: string]: string[] };
    isDynamicEntry: boolean;
    isEntry: boolean;
    isImplicitEntry: boolean;
    map: SourceMap | null;
    modules: {
        [id: string]: {
            renderedExports: string[];
            removedExports: string[];
            renderedLength: number;
            originalLength: number;
            code: string | null;
        };
    };
    moduleIds: string[];
    name: string;
    preliminaryFileName: string;
    referencedFiles: string[];
    sourcemapFileName: string | null;
    type: 'chunk';
}

在 bundle.generate() 结束时或在 bundle.write() 写入文件之前立即调用。

要在写入文件后修改文件，请使用 writeBundle 钩子。bundle 提供正在写入或生成的文件的完整列表以及它们的详细信息。

可以通过在此钩子中从产物对象中删除它们来防止文件被产出。要产出其他文件，请使用 this.emitFile 插件上下文函数。

delete bundle[file.name] 可以阻止产出

{
	generateBundle(output, bundle) {
		delete bundle['dist.js']
	}
}

writeBundle

(options: OutputOptions, bundle: { [fileName: string]: AssetInfo \| ChunkInfo }) => void

仅在 bundle.write() 结束时调用，一旦所有文件都已写入。与 generateBundle 钩子类似，bundle 提供正在写入的所有文件的完整列表以及它们的详细信息。

closeBundle

closeBundle: () => Promise<void> \| void

可用于清理可能正在运行的任何外部服务。Rollup 的 CLI 将确保在每次运行后调用此钩子，但是 JavaScript API 的用户有责任在生成产物后手动调用 bundle.close()。因此，任何依赖此功能的插件都应在其文档中仔细提到这一点。

如果插件想要在监视模式下保留资源，则可以在此钩子中检查 this.meta.watchMode 并在 closeWatcher 中执行必要的监视模式清理。

renderError

renderError: (error: Error) => void

当 rollup 在bundle.generate()或bundle.write()期间遇到错误时调用。将错误传递给此钩子。要在生成成功完成时得到通知，请使用generateBundle钩子。