feat(cjs): warn when platform is ignored for the CJS format (#1111)

Co-authored-by: Kevin Bot <gh-bot@sxzz.moe>

Author: sxzz

AGENTS.md

@@ -177,7 +177,7 @@ Each feature is self-contained and modular:
 
 Plugins follow Rolldown's interface. Internal plugins are added based on config, user plugins append last. User plugins may additionally implement tsdown-specific hooks (`tsdownConfig` to modify user config before resolution, `tsdownConfigResolved` to read the resolved config) — see `src/features/plugin.ts`. The build supports dual-format output (ESM + CJS) with a second pass for CJS type declarations (`cjsDts`).
 
-Public plugin exports in `src/plugins.ts`: `DepsPlugin`, `NodeProtocolPlugin`, `ReportPlugin`, `ShebangPlugin`, `WatchPlugin`
+Public plugin exports in `src/plugins.ts`: `DepsPlugin`, `NodeProtocolPlugin`, `ReportPlugin`, `ShebangPlugin`, `ShimsPlugin`, `WatchPlugin`
 
 ### Key Architectural Patterns
 

__snapshots__/tsnapi/plugins.snapshot.d.ts

@@ -6,5 +6,6 @@ export declare function DepsPlugin({ pkg, deps: { neverBundle, alwaysBundle: jsA
 export declare function NodeProtocolPlugin(_: "strip" | true): Plugin;
 export declare function ReportPlugin(_: ResolvedConfig, _?: boolean, _?: boolean): Plugin;
 export declare function ShebangPlugin(_: Logger, _: string, _?: string, _?: boolean): Plugin;
+export declare function ShimsPlugin(_: ResolvedConfig, _: NormalizedFormat): Plugin;
 export declare function WatchPlugin(_: Set<string>, { config, chunks }: TsdownBundle): Plugin;
 // #endregion

__snapshots__/tsnapi/plugins.snapshot.js

@@ -6,5 +6,6 @@ export function DepsPlugin(_, _) {}
 export function NodeProtocolPlugin(_) {}
 export function ReportPlugin(_, _, _) {}
 export function ShebangPlugin(_, _, _, _) {}
+export function ShimsPlugin(_, _) {}
 export function WatchPlugin(_, _) {}
 // #endregion

docs/options/platform.md

@@ -17,7 +17,7 @@ tsdown --platform neutral
 - **`neutral`:** A platform-agnostic target with no specific runtime assumptions. Use this if your code is intended to run in multiple environments or you want full control over runtime behavior. This is particularly useful for libraries or shared code that may be used in both Node.js and browser environments.
 
 > [!NOTE]
-> For the CJS format, the platform is always set to `'node'` and cannot be changed. [Why?](https://github.com/rolldown/rolldown/pull/4693#issuecomment-2912229545)
+> For the CJS format, the platform is always set to `'node'`, and tsdown warns if you set `'browser'`. [Why?](https://github.com/rolldown/rolldown/pull/4693#issuecomment-2912229545) Use `platform: 'neutral'` if your code isn't browser-only, or set `inputOptions: { platform: 'browser' }` to build CJS for the browser anyway.
 
 ### Example
 

docs/zh-CN/options/platform.md

@@ -17,7 +17,7 @@ tsdown --platform neutral
 - **`neutral`：** 与平台无关的目标，不对特定运行时环境做假设。如果您的代码需要在多个环境中运行，或者您希望完全控制运行时行为，可以选择此选项。特别适合用于 Node.js 和浏览器环境的库或共享代码。
 
 > [!NOTE]
-> 对于 CJS 格式，平台始终为 `'node'`，无法更改。 [为什么？](https://github.com/rolldown/rolldown/pull/4693#issuecomment-2912229545)
+> 对于 CJS 格式，平台始终为 `'node'`，设置为 `'browser'` 时 tsdown 会发出警告。 [为什么？](https://github.com/rolldown/rolldown/pull/4693#issuecomment-2912229545) 如果代码不只用于浏览器，请使用 `platform: 'neutral'`；如果仍需要为浏览器构建 CJS，可以设置 `inputOptions: { platform: 'browser' }`。
 
 ### 示例
 

skills/tsdown/references/option-platform.md

@@ -91,13 +91,23 @@ export default defineConfig({
 
 ## CJS Format Limitation
 
-**CJS format always uses `node` platform** and cannot be changed.
+**CJS format always uses `node` platform**, and tsdown warns when `platform: 'browser'` is set.
 
 ```ts
 export default defineConfig({
   entry: ['src/index.ts'],
   format: ['cjs'],
-  platform: 'browser',  // Ignored for CJS
+  platform: 'browser',  // Ignored for CJS, with a warning
+})
+```
+
+Use `platform: 'neutral'` if the code isn't browser-only. To force the browser platform for CJS, override it via `inputOptions`:
+
+```ts
+export default defineConfig({
+  format: ['cjs'],
+  platform: 'browser',
+  inputOptions: { platform: 'browser' },
 })
 ```
 

src/features/cjs.test.ts

@@ -0,0 +1,58 @@
+import { describe, expect, test, vi } from 'vitest'
+import { warnCjsPlatform } from './cjs.ts'
+import type { ResolvedConfig } from '../config/types.ts'
+import type { InputOptions } from 'rolldown'
+
+function run(config: Partial<ResolvedConfig>, inputOptions: InputOptions) {
+  const warnOnce = vi.fn()
+  warnCjsPlatform(
+    { logger: { warnOnce }, ...config } as unknown as ResolvedConfig,
+    inputOptions,
+  )
+  return warnOnce
+}
+
+describe('warnCjsPlatform', () => {
+  test('warns when cjs is built for a non-node platform', () => {
+    const warnOnce = run(
+      { format: 'cjs', platform: 'browser' },
+      { platform: 'node' },
+    )
+    expect(warnOnce).toHaveBeenCalledOnce()
+    expect(warnOnce.mock.calls[0].join(' ')).toContain(
+      "`platform: 'browser'` is ignored",
+    )
+  })
+
+  test('does not warn when the platform is forced via inputOptions', () => {
+    const warnOnce = run(
+      { format: 'cjs', platform: 'browser' },
+      { platform: 'browser' },
+    )
+    expect(warnOnce).not.toHaveBeenCalled()
+  })
+
+  test('does not warn for the neutral platform', () => {
+    const warnOnce = run(
+      { format: 'cjs', platform: 'neutral' },
+      { platform: 'node' },
+    )
+    expect(warnOnce).not.toHaveBeenCalled()
+  })
+
+  test('does not warn for the node platform', () => {
+    const warnOnce = run(
+      { format: 'cjs', platform: 'node' },
+      { platform: 'node' },
+    )
+    expect(warnOnce).not.toHaveBeenCalled()
+  })
+
+  test('does not warn for other formats', () => {
+    const warnOnce = run(
+      { format: 'es', platform: 'browser' },
+      { platform: 'browser' },
+    )
+    expect(warnOnce).not.toHaveBeenCalled()
+  })
+})

src/features/cjs.ts

@@ -1,5 +1,6 @@
 import { coerce, parseRange, satisfies } from 'verkit'
 import type { ResolvedConfig } from '../config/index.ts'
+import type { InputOptions } from 'rolldown'
 
 const RANGE_REQUIRING_ESM = parseRange('^20.19.0 || >=22.12.0')
 
@@ -27,3 +28,25 @@ export function warnLegacyCJS(config: ResolvedConfig): void {
     )
   }
 }
+
+export function warnCjsPlatform(
+  config: ResolvedConfig,
+  inputOptions: InputOptions,
+): void {
+  if (
+    config.format !== 'cjs' ||
+    // `neutral` makes no runtime assumptions, so building CJS for Node.js is expected
+    config.platform !== 'browser' ||
+    // the user forced another platform via `inputOptions`
+    inputOptions.platform !== 'node'
+  ) {
+    return
+  }
+
+  config.logger.warnOnce(
+    config.nameLabel,
+    "The `cjs` format always targets Node.js, so `platform: 'browser'` is ignored for it.\n" +
+      "Use `platform: 'neutral'` if the code isn't browser-only, " +
+      "or set `inputOptions: { platform: 'browser' }` to build CJS for the browser anyway.",
+  )
+}

src/features/rolldown.ts

@@ -21,12 +21,13 @@ import pkg from '../../package.json' with { type: 'json' }
 import { mergeUserOptions } from '../config/options.ts'
 import { importWithError, pkgExists, toArray } from '../utils/general.ts'
 import { createSuppressWarnings, LogLevels } from '../utils/logger.ts'
+import { warnCjsPlatform } from './cjs.ts'
 import { DepsPlugin } from './deps.ts'
 import { NodeProtocolPlugin } from './node-protocol.ts'
 import { resolveChunkAddon, resolveChunkFilename } from './output.ts'
 import { ReportPlugin } from './report.ts'
 import { ShebangPlugin } from './shebang.ts'
-import { getShims } from './shims.ts'
+import { ShimsPlugin } from './shims.ts'
 import { WatchPlugin } from './watch.ts'
 import type {
   DtsOptions,
@@ -53,6 +54,7 @@ export async function getBuildOptions(
     cjsDts,
     isDualFormat,
   )
+  if (!cjsDts) warnCjsPlatform(config, inputOptions)
 
   const outputOptions: OutputOptions = await resolveOutputOptions(
     inputOptions,
@@ -102,7 +104,6 @@ async function resolveInputOptions(
     platform,
     plugins: userPlugins,
     report,
-    shims,
     target,
     treeshake,
     tsconfig,
@@ -194,7 +195,7 @@ async function resolveInputOptions(
     plugins.push(...cssPostPlugins)
   }
 
-  let define: TransformOptions['define'] = {
+  const define: TransformOptions['define'] = {
     ...config.define,
     ...Object.keys(env).reduce((acc, key) => {
       const value = JSON.stringify(env[key])
@@ -204,14 +205,8 @@ async function resolveInputOptions(
     }, Object.create(null)),
   }
 
-  let inject: TransformOptions['inject']
-  if (shims && !cjsDts) {
-    const shims = getShims(config)
-    inject = shims.inject
-    define = { ...define, ...shims.define }
-    if (shims.plugin) {
-      plugins.push(shims.plugin)
-    }
+  if (!cjsDts) {
+    plugins.push(ShimsPlugin(config, format))
   }
 
   // `neverBundle: true` is handled by DepsPlugin instead of rolldown's
@@ -261,7 +256,6 @@ async function resolveInputOptions(
       transform: {
         target,
         define,
-        inject,
       },
       plugins,
       moduleTypes: {

src/features/shims.ts

@@ -1,5 +1,6 @@
 import path from 'node:path'
 import type { ResolvedConfig } from '../config/index.ts'
+import type { NormalizedFormat } from '../config/types.ts'
 import type { Plugin } from 'rolldown'
 
 export const shimFile: string = path.resolve(
@@ -26,24 +27,44 @@ const __TSDOWN_SHIM_FILENAME__ = /* @__PURE__ */ __tsdown_shims_url.fileURLToPat
 const __TSDOWN_SHIM_DIRNAME__ = /* @__PURE__ */ __tsdown_shims_path.dirname(__TSDOWN_SHIM_FILENAME__)
 `
 
-export const shimsPlugin: Plugin = {
-  name: 'tsdown:shims-banner',
-  banner: shimsInjectCode,
+const cjsImportMetaDefine: Record<string, string> = {
+  'import.meta.url': 'require("url").pathToFileURL(__filename).href',
+  'import.meta.filename': '__filename',
+  'import.meta.dirname': '__dirname',
 }
 
-export function getShims(config: ResolvedConfig): {
-  define?: Record<string, string>
-  inject?: Record<string, [string, string]>
-  plugin?: Plugin
-} {
-  if (config.format !== 'es' || config.platform !== 'node') return {}
-
-  if (config.unbundle) {
-    return {
-      define: shimsDefine,
-      plugin: shimsPlugin,
-    }
-  }
+/**
+ * Shims are decided in the `options` hook, from the final `platform` after the
+ * user's `inputOptions` are merged.
+ */
+export function ShimsPlugin(
+  config: ResolvedConfig,
+  format: NormalizedFormat,
+): Plugin {
+  let banner = false
+
+  return {
+    name: 'tsdown:shims',
+    options(options) {
+      const isNode = options.platform === 'node'
+      const transform = (options.transform ||= {})
 
-  return { inject: shimsInject }
+      // Rolldown only rewrites `import.meta` for CJS on the node platform
+      if (format === 'cjs') {
+        if (!isNode) {
+          transform.define = { ...cjsImportMetaDefine, ...transform.define }
+        }
+        return
+      }
+
+      if (format !== 'es' || !config.shims || !isNode) return
+      if (config.unbundle) {
+        transform.define = { ...transform.define, ...shimsDefine }
+        banner = true
+      } else {
+        transform.inject = { ...transform.inject, ...shimsInject }
+      }
+    },
+    banner: () => (banner ? shimsInjectCode : ''),
+  }
 }