feat: add banner & footer options (#338)

gwansikk · sxzz · web-flow · commit 54e21e13ff44 · 2025-07-18T09:55:11.000Z
Co-authored-by: 三咲智子 Kevin Deng &lt;sxzz@sxzz.moe&gt;
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
diff --git a/pnpm-workspace.yaml b/pnpm-workspace.yaml
@@ -3,7 +3,7 @@ catalogs:
     '@arethetypeswrong/core': ^0.18.2
     '@sxzz/eslint-config': ^7.0.6
     '@sxzz/prettier-config': ^2.2.3
-    '@sxzz/test-utils': ^0.5.6
+    '@sxzz/test-utils': ^0.5.7
     '@types/debug': ^4.1.12
     '@types/node': ^24.0.14
     '@types/semver': ^7.7.0
diff --git a/src/features/output.ts b/src/features/output.ts
@@ -1,6 +1,12 @@
+import { RE_CSS, RE_DTS, RE_JS } from 'rolldown-plugin-dts/filename'
 import { getPackageType, type PackageType } from '../utils/package'
-import type { NormalizedFormat, ResolvedOptions } from '../options'
-import type { InputOptions, PreRenderedChunk } from 'rolldown'
+import type { Format, NormalizedFormat, ResolvedOptions } from '../options'
+import type {
+  AddonFunction,
+  InputOptions,
+  PreRenderedChunk,
+  RenderedChunk,
+} from 'rolldown'
 
 export interface OutExtensionContext {
   options: InputOptions
@@ -76,3 +82,37 @@ function createChunkFilename(
     return `${basename}${chunk.name.endsWith('.d') ? dtsExtension : jsExtension}`
   }
 }
+
+export interface ChunkAddonObject {
+  js?: string
+  css?: string
+  dts?: string
+}
+export type ChunkAddonFunction = (ctx: {
+  format: Format
+}) => ChunkAddonObject | undefined
+export type ChunkAddon = ChunkAddonObject | ChunkAddonFunction
+
+export function resolveChunkAddon(
+  chunkAddon: ChunkAddon | undefined,
+  format: NormalizedFormat,
+): AddonFunction | undefined {
+  if (!chunkAddon) return
+
+  return (chunk: RenderedChunk) => {
+    if (typeof chunkAddon === 'function') {
+      chunkAddon = chunkAddon({ format })
+    }
+
+    switch (true) {
+      case RE_JS.test(chunk.fileName):
+        return chunkAddon?.js || ''
+      case RE_CSS.test(chunk.fileName):
+        return chunkAddon?.css || ''
+      case RE_DTS.test(chunk.fileName):
+        return chunkAddon?.dts || ''
+      default:
+        return ''
+    }
+  }
+}
diff --git a/src/index.ts b/src/index.ts
@@ -19,7 +19,7 @@ import { ExternalPlugin } from './features/external'
 import { createHooks } from './features/hooks'
 import { LightningCSSPlugin } from './features/lightningcss'
 import { NodeProtocolPlugin } from './features/node-protocol'
-import { resolveChunkFilename } from './features/output'
+import { resolveChunkAddon, resolveChunkFilename } from './features/output'
 import { publint } from './features/publint'
 import { ReportPlugin } from './features/report'
 import { getShimsInject } from './features/shims'
@@ -215,6 +215,8 @@ async function getBuildOptions(
     loader,
     name,
     unbundle,
+    banner,
+    footer,
   } = config
 
   const plugins: RolldownPluginOption = []
@@ -312,6 +314,8 @@ async function getBuildOptions(
       preserveModulesRoot: unbundle
         ? lowestCommonAncestor(...Object.values(entry))
         : undefined,
+      banner: resolveChunkAddon(banner, format),
+      footer: resolveChunkAddon(footer, format),
     },
     config.outputOptions,
     [format],
diff --git a/src/options/types.ts b/src/options/types.ts
@@ -2,7 +2,7 @@ import type { AttwOptions } from '../features/attw'
 import type { CopyOptions, CopyOptionsFn } from '../features/copy'
 import type { ExportsOptions } from '../features/exports'
 import type { TsdownHooks } from '../features/hooks'
-import type { OutExtensionFactory } from '../features/output'
+import type { ChunkAddon, OutExtensionFactory } from '../features/output'
 import type { ReportOptions } from '../features/report'
 import type {
   Arrayable,
@@ -359,6 +359,8 @@ export interface Options {
    * Filter workspace packages. This option is only available in workspace mode.
    */
   filter?: RegExp | string | string[]
+  footer?: ChunkAddon
+  banner?: ChunkAddon
 }
 
 /**
@@ -389,6 +391,8 @@ export type ResolvedOptions = Omit<
       | 'loader'
       | 'name'
       | 'bundle'
+      | 'banner'
+      | 'footer'
     >,
     {
       format: NormalizedFormat[]
diff --git a/tests/__snapshots__/banner-and-footer-option.snap.md b/tests/__snapshots__/banner-and-footer-option.snap.md
@@ -0,0 +1,15 @@
+## index.d.ts
+
+```ts
+export { };
+```
+## index.js
+
+```js
+// js banner
+//#region index.ts
+console.log("Hello, world!");
+
+//#endregion
+// js footer
+```
diff --git a/tests/index.test.ts b/tests/index.test.ts
@@ -408,3 +408,30 @@ test('workspace option', async (context) => {
     expectPattern: '**/dist',
   })
 })
+
+test('banner and footer option', async (context) => {
+  const content = `console.log("Hello, world!")`
+  const { fileMap } = await testBuild({
+    context,
+    files: {
+      'index.ts': content,
+    },
+    options: {
+      dts: true,
+      banner: {
+        js: '// js banner',
+        dts: '// dts banner',
+      },
+      footer: {
+        js: '// js footer',
+        dts: '// dts footer',
+      },
+    },
+  })
+
+  expect(fileMap['index.js']).toContain('// js banner')
+  expect(fileMap['index.js']).toContain('// js footer')
+
+  // expect(fileMap['index.d.ts']).toContain('// dts banner')
+  // expect(fileMap['index.d.ts']).toContain('// dts footer')
+})
diff --git a/tests/utils.ts b/tests/utils.ts
@@ -122,6 +122,7 @@ export async function testBuild({
   outputFiles: string[]
   outputDir: string
   snapshot: string
+  fileMap: Record<string, string>
 }> {
   const { expect } = context
   const { testName, testDir } = await writeFixtures(context, files, fixture)
@@ -141,7 +142,11 @@ export async function testBuild({
   restoreCwd()
 
   const outputDir = path.resolve(workingDir, resolvedOptions.outDir!)
-  const { files: outputFiles, snapshot } = await expectFilesSnapshot(
+  const {
+    files: outputFiles,
+    snapshot,
+    fileMap,
+  } = await expectFilesSnapshot(
     path.resolve(outputDir, expectDir),
     path.resolve(snapshotsDir, `${testName}.snap.md`),
     { pattern: expectPattern, expect },
@@ -153,6 +158,7 @@ export async function testBuild({
     outputFiles,
     outputDir,
     snapshot,
+    fileMap,
   }
 }
 
