feat(bun): sanitize plugin names for namespaces (#599)

81reap · web-flow · commit 94dadfe73abb · 2026-05-23T11:27:07.000+09:00
Bun only allows `\w`, `$`, and `-` in plugin namespaces, so coerce unsupported characters in `plugin.name` to `-` before using it as a namespace.

MINOR BREAKING CHANGE: Sanitized plugin names may have namespace collisions if existing plugins map to the same name.
diff --git a/src/bun/index.ts b/src/bun/index.ts
@@ -6,6 +6,12 @@ import { normalizeObjectHook } from '../utils/filter'
 import { toArray } from '../utils/general'
 import { createBuildContext, createPluginContext, guessLoader } from './utils'
 
+// Coerce plugin.name to satisfy Bun's namespace validator:
+// https://github.com/oven-sh/bun/blob/12d77d1ac561771e9fa1d0822e954273248e7f9a/src/js/builtins/BundlerPlugin.ts#L215-L217
+function toBunNamespace(name: string): string {
+  return name.replace(/[^\w$-]/g, '-')
+}
+
 export function getBunPlugin<UserOptions = Record<string, never>>(
   factory: UnpluginFactory<UserOptions>,
 ): UnpluginInstance<UserOptions>['bun'] {
@@ -106,7 +112,7 @@ export function getBunPlugin<UserOptions = Record<string, never>>(
                 if (!isAbsolute(result)) {
                   return {
                     path: result,
-                    namespace: plugin.name,
+                    namespace: toBunNamespace(plugin.name),
                   }
                 }
                 return { path: result }
@@ -116,7 +122,7 @@ export function getBunPlugin<UserOptions = Record<string, never>>(
                   return {
                     path: result.id,
                     external: result.external,
-                    namespace: plugin.name,
+                    namespace: toBunNamespace(plugin.name),
                   }
                 }
                 return {
@@ -221,7 +227,7 @@ export function getBunPlugin<UserOptions = Record<string, never>>(
         }
 
         for (const pluginName of virtualModulePlugins) {
-          build.onLoad({ filter: /.*/, namespace: pluginName }, async (args) => {
+          build.onLoad({ filter: /.*/, namespace: toBunNamespace(pluginName) }, async (args) => {
             return processLoadTransform(args.path, pluginName, args.loader)
           })
         }
diff --git a/test/unit-tests/bun/namespace.test.ts b/test/unit-tests/bun/namespace.test.ts
@@ -0,0 +1,126 @@
+import { createUnplugin } from 'unplugin'
+import { describe, expect, it, vi } from 'vitest'
+
+interface MockBuild {
+  build: Bun.PluginBuilder
+  resolveCallback: () => Bun.OnResolveCallback
+  loadCallbacks: Map<string, Bun.OnLoadCallback>
+}
+
+function createMockBuild(): MockBuild {
+  let resolveCallback: Bun.OnResolveCallback | undefined
+  const loadCallbacks = new Map<string, Bun.OnLoadCallback>()
+
+  const build = {
+    onResolve: vi.fn((_options, callback) => {
+      resolveCallback = callback
+    }),
+    onLoad: vi.fn((options: { namespace?: string }, callback: Bun.OnLoadCallback) => {
+      if (options.namespace) {
+        loadCallbacks.set(options.namespace, callback)
+      }
+    }),
+    onStart: vi.fn(),
+    config: { outdir: './dist' },
+  } as never as Bun.PluginBuilder
+
+  return {
+    build,
+    resolveCallback: () => {
+      if (!resolveCallback) {
+        throw new Error('onResolve was not registered')
+      }
+      return resolveCallback
+    },
+    loadCallbacks,
+  }
+}
+
+describe.skipIf(typeof Bun === 'undefined')('bun namespace sanitization', () => {
+  it('should sanitize invalid characters when resolveId returns a string', async () => {
+    const unplugin = createUnplugin(() => ({
+      name: 'unplugin:my.plugin/name',
+      resolveId: () => 'virtual-id',
+    }))
+    const { build, resolveCallback } = createMockBuild()
+
+    await unplugin.bun().setup(build)
+    const result = await resolveCallback()({
+      path: 'foo',
+      importer: 'index.js',
+      kind: 'import-statement',
+    } as Bun.OnResolveArgs)
+
+    expect(result).toEqual({
+      path: 'virtual-id',
+      namespace: 'unplugin-my-plugin-name',
+    })
+  })
+
+  it('should sanitize invalid characters when resolveId returns an object', async () => {
+    const unplugin = createUnplugin(() => ({
+      name: '@scope/plugin.name',
+      resolveId: () => ({ id: 'virtual-id', external: false }),
+    }))
+    const { build, resolveCallback } = createMockBuild()
+
+    await unplugin.bun().setup(build)
+    const result = await resolveCallback()({
+      path: 'foo',
+      importer: 'index.js',
+      kind: 'import-statement',
+    } as Bun.OnResolveArgs)
+
+    expect(result).toEqual({
+      path: 'virtual-id',
+      external: false,
+      namespace: '-scope-plugin-name',
+    })
+  })
+
+  it('should leave plugin names with only allowed characters untouched', async () => {
+    const unplugin = createUnplugin(() => ({
+      name: 'valid_plugin-name$1',
+      resolveId: () => 'virtual-id',
+    }))
+    const { build, resolveCallback } = createMockBuild()
+
+    await unplugin.bun().setup(build)
+    const result = await resolveCallback()({
+      path: 'foo',
+      importer: 'index.js',
+      kind: 'import-statement',
+    } as Bun.OnResolveArgs)
+
+    expect(result).toEqual({
+      path: 'virtual-id',
+      namespace: 'valid_plugin-name$1',
+    })
+  })
+
+  it('should invoke the original load hook when registered under a sanitized namespace', async () => {
+    const load = vi.fn(() => 'export default 1')
+    const unplugin = createUnplugin(() => ({
+      name: 'unplugin:virtual.mod',
+      resolveId: () => 'virtual-id',
+      load,
+    }))
+    const { build, loadCallbacks } = createMockBuild()
+
+    await unplugin.bun().setup(build)
+
+    expect([...loadCallbacks.keys()]).toContain('unplugin-virtual-mod')
+    expect([...loadCallbacks.keys()]).not.toContain('unplugin:virtual.mod')
+
+    const result = await loadCallbacks.get('unplugin-virtual-mod')!({
+      path: 'virtual-id',
+      loader: 'js',
+    } as Bun.OnLoadArgs)
+
+    expect(load).toHaveBeenCalledWith('virtual-id')
+    expect(result).toEqual({
+      contents: 'export default 1',
+      loader: 'js',
+    })
+  })
+})
