rollup-plugin-keep-header-comment

API Documents

English · 简体中文

A rollup plugin to keep the first comment or one that match the provided pattern from the source code at the start of the bundle file.

When I try to use tsdoc and @microsoft/api-extractor、@microsoft/api-documenter to generate docs for my project without --local flag，I got Warning: dist/index.d.ts:4:1 - (ae-misplaced-package-tag) The @packageDocumentation comment must appear at the top of entry point *.d.ts file. However rollup will put the import statements at the start of the file no matter where I place the package documentation comment.

So I develop this plugin fot those who want to use rollup and tsdoc, you can now put this plugin after the one that generate .d.ts file in rollup config. See example in Usage or Doc.

Install

install npm package

npm install gridfs-extra

or clone from Github

# ssh
git clone git@github.com:peachest/gridfs-extra.git

# http
git clone https://github.com/peachest/gridfs-extra.git

Usage

Put this plugin at the last after the dts plugin

import clear from "rollup-plugin-clear";
import json from "@rollup/plugin-json";
import nodeResolve from "@rollup/plugin-node-resolve";
import commonjs from "@rollup/plugin-commonjs";
import typescript from "rollup-plugin-typescript2";
import dts from "rollup-plugin-dts";
import keepHeaderComment from "rollup-plugin-keep-header-comment";

export default {
  plugins: [
    clear({targets: ["dist"]}),
    json(),
    nodeResolve({preferBuiltins: false}),
    commonjs(),
    typescript({tsconfig}),
    dts({tsconfig}),
    keepHeaderComment({
        sourcemap: true,
        pattern: /@packageDocumentation/
    })
  ]
}

Now you can put your packageDocumentation comment wherever you want in your source code:

import { OutputPlugin } from 'rollup';
/**
 * A rollup plugin to keep the header comments from source in the declaration file
 * @packageDocumentation
 */

rollup will generate dist/index.d.ts with comment at the start:

/**
 * A rollup plugin to keep the header comments from source in the declaration file
 * @packageDocumentation
 */
import { OutputPlugin } from 'rollup';

options：

• sourcemap（optional）：generate sourcemap for rollup, won’t generate sourcemap file in output directory

• pattern（optional）: if provided, comment which match this pattern will be shifted to the start of the file, otherwise the first comment will be shifted