feat: add banner & footer option

sxzz · sxzz · commit f999bc9d970f · 2025-09-12T23:34:00.000+09:00
diff --git a/README.md b/README.md
@@ -99,6 +99,14 @@ If set to `true`, and you are only exporting a single item using `export default
 the output will use `export = ...` instead of the standard ES module syntax.
 This is useful for compatibility with CommonJS.
 
+#### `banner`
+
+Content to be added at the top of each generated `.d.ts` file.
+
+#### `footer`
+
+Content to be added at the bottom of each generated `.d.ts` file.
+
 ### `tsc` Options
 
 > [!NOTE]
diff --git a/package.json b/package.json
@@ -80,7 +80,8 @@
     "birpc": "^2.5.0",
     "debug": "^4.4.1",
     "dts-resolver": "^2.1.2",
-    "get-tsconfig": "^4.10.1"
+    "get-tsconfig": "^4.10.1",
+    "magic-string": "^0.30.19"
   },
   "devDependencies": {
     "@sxzz/eslint-config": "^7.1.4",
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
diff --git a/src/banner.ts b/src/banner.ts
@@ -0,0 +1,43 @@
+import MagicString from 'magic-string'
+import { RE_DTS } from './filename.ts'
+import type { OptionsResolved } from './options.ts'
+import type { Plugin } from 'rolldown'
+
+export function createBannerPlugin({
+  banner,
+  footer,
+}: Pick<OptionsResolved, 'banner' | 'footer'>): Plugin {
+  return {
+    name: 'rolldown-plugin-dts:banner',
+    async renderChunk(code: string, chunk) {
+      if (!RE_DTS.test(chunk.fileName)) {
+        return
+      }
+
+      const s = new MagicString(code)
+      if (banner) {
+        const code = await (typeof banner === 'function'
+          ? banner(chunk)
+          : banner)
+        if (code) s.prepend(`${code}\n`)
+      }
+      if (footer) {
+        const code = await (typeof footer === 'function'
+          ? footer(chunk)
+          : footer)
+        if (code) s.append(`\n${code}`)
+      }
+
+      return {
+        code: s.toString(),
+        get map() {
+          return s.generateMap({
+            source: chunk.fileName,
+            includeContent: true,
+            hires: 'boundary',
+          })
+        },
+      }
+    },
+  }
+}
diff --git a/src/index.ts b/src/index.ts
@@ -1,5 +1,5 @@
 import Debug from 'debug'
-
+import { createBannerPlugin } from './banner.ts'
 import { createDtsInputPlugin } from './dts-input.ts'
 import { createFakeJsPlugin } from './fake-js.ts'
 import { createGeneratePlugin } from './generate.ts'
@@ -31,6 +31,9 @@ export function dts(options: Options = {}): Plugin[] {
     plugins.push(createGeneratePlugin(resolved))
   }
   plugins.push(createDtsResolvePlugin(resolved), createFakeJsPlugin(resolved))
+  if (options.banner || options.footer) {
+    plugins.push(createBannerPlugin(resolved))
+  }
   return plugins
 }
 
diff --git a/src/options.ts b/src/options.ts
@@ -6,6 +6,7 @@ import {
   type TsConfigJson,
   type TsConfigJsonResolved,
 } from 'get-tsconfig'
+import type { AddonFunction } from 'rolldown'
 import type { IsolatedDeclarationsOptions } from 'rolldown/experimental'
 
 //#region General Options
@@ -166,6 +167,15 @@ export interface TscOptions {
    * `false`.
    */
   emitJs?: boolean
+
+  /**
+   * Content to be added at the top of each generated `.d.ts` file.
+   */
+  banner?: string | Promise<string> | AddonFunction
+  /**
+   * Content to be added at the bottom of each generated `.d.ts` file.
+   */
+  footer?: string | Promise<string> | AddonFunction
 }
 
 export interface Options extends GeneralOptions, TscOptions {
@@ -193,11 +203,13 @@ export interface Options extends GeneralOptions, TscOptions {
 }
 
 type Overwrite<T, U> = Pick<T, Exclude<keyof T, keyof U>> & U
+type MarkPartial<T, K extends keyof T> = Omit<Required<T>, K> &
+  Partial<Pick<T, K>>
 
 export type OptionsResolved = Overwrite<
-  Required<Omit<Options, 'compilerOptions'>>,
+  MarkPartial<Omit<Options, 'compilerOptions'>, 'banner' | 'footer'>,
   {
-    tsconfig: string | undefined
+    tsconfig?: string
     oxc: IsolatedDeclarationsOptions | false
     tsconfigRaw: TsConfigJson
   }
@@ -215,6 +227,8 @@ export function resolveOptions({
   sourcemap,
   resolve = false,
   cjsDefault = false,
+  banner,
+  footer,
 
   // tsc
   build = false,
@@ -313,6 +327,8 @@ export function resolveOptions({
     sourcemap,
     resolve,
     cjsDefault,
+    banner,
+    footer,
 
     // tsc
     build,
diff --git a/tests/__snapshots__/index.test.ts.snap b/tests/__snapshots__/index.test.ts.snap
@@ -1,5 +1,15 @@
 // Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
 
+exports[`banner 1`] = `
+"// minimal.d.ts
+/* My Banner */
+//#region tests/fixtures/minimal.d.ts
+declare function foo(): void;
+//#endregion
+export { foo };
+/* My Footer minimal.d.ts */"
+`;
+
 exports[`basic 1`] = `
 "// basic.d.ts
 //#region tests/fixtures/basic.d.ts
diff --git a/tests/fixtures/minimal.ts b/tests/fixtures/minimal.ts
@@ -0,0 +1 @@
+export function foo(): void {}
diff --git a/tests/index.test.ts b/tests/index.test.ts
@@ -456,3 +456,19 @@ test('should error when file import cannot be found', async () => {
     ]),
   ).rejects.toThrow("Could not resolve './missing-file'")
 })
+
+test('banner', async () => {
+  const { snapshot } = await rolldownBuild(
+    path.resolve(dirname, 'fixtures/minimal.ts'),
+    [
+      dts({
+        emitDtsOnly: true,
+        banner: '/* My Banner */',
+        footer: (chunk) => `/* My Footer ${chunk.fileName} */`,
+      }),
+    ],
+  )
+  expect(snapshot).toMatchSnapshot()
+  expect(snapshot).toContain('/* My Banner */\n')
+  expect(snapshot).toContain('\n/* My Footer minimal.d.ts */')
+})
