feat(rolldown): add isRolldownMagicString property for reliable native detection (#8614)

IWANABETHATGUY · IWANABETHATGUY · commit b08184ef5fd6 · 2026-03-10T14:55:16.000Z
## Summary External packages like `rolldown-string` need to detect native `BindingMagicString` instances, but the existing `obj.constructor.name` check breaks under minification or bundling. This PR adds a reliable `isRolldownMagicString` boolean property to the `BindingMagicString` prototype via `Object.defineProperty` (non-writable, non-configurable). A new `binding-magic-string.ts` module centralizes the patching and re-exports the class with proper TypeScript typings. All internal imports now go through this module to ensure consistency. Tests cover prototype presence, instance access, and detection without importing rolldown. ## Related #7522 🤖 Generated with [Claude Code](https://claude.com/claude-code)
diff --git a/packages/rolldown/src/binding-magic-string.ts b/packages/rolldown/src/binding-magic-string.ts
@@ -0,0 +1,23 @@
+import { BindingMagicString as NativeBindingMagicString } from './binding.cjs';
+
+// Set `isRolldownMagicString` so external packages (e.g. rolldown-string) can
+// detect native BindingMagicString instances without importing rolldown:
+//   obj.isRolldownMagicString === true
+// This replaces the fragile `obj.constructor.name` check which breaks with
+// minification or bundling.
+Object.defineProperty(NativeBindingMagicString.prototype, 'isRolldownMagicString', {
+  value: true,
+  writable: false,
+  configurable: false,
+});
+
+export interface BindingMagicString extends NativeBindingMagicString {
+  readonly isRolldownMagicString: true;
+}
+
+type BindingMagicStringConstructor = Omit<typeof NativeBindingMagicString, 'prototype'> & {
+  new (...args: ConstructorParameters<typeof NativeBindingMagicString>): BindingMagicString;
+  prototype: BindingMagicString;
+};
+
+export const BindingMagicString = NativeBindingMagicString as BindingMagicStringConstructor;
diff --git a/packages/rolldown/src/index.ts b/packages/rolldown/src/index.ts
@@ -3,6 +3,7 @@ import { build, type BuildOptions } from './api/build';
 import { rolldown } from './api/rolldown';
 import type { RolldownBuild } from './api/rolldown/rolldown-build';
 import { watch } from './api/watch';
+import { BindingMagicString } from './binding-magic-string';
 import type {
   RolldownWatcher,
   RolldownWatcherEvent,
@@ -118,7 +119,7 @@ import type { BundleError } from './utils/error';
 
 export { RUNTIME_MODULE_ID, VERSION } from './constants';
 export { build, defineConfig, rolldown, watch };
-export { BindingMagicString } from './binding.cjs';
+export { BindingMagicString };
 export type {
   AddonFunction,
   BundleError,
diff --git a/packages/rolldown/src/plugin/bindingify-build-hooks.ts b/packages/rolldown/src/plugin/bindingify-build-hooks.ts
@@ -6,7 +6,7 @@ import type {
   BindingPluginContext,
   BindingPluginOptions,
 } from '../binding.cjs';
-import { BindingMagicString } from '../binding.cjs';
+import { BindingMagicString } from '../binding-magic-string';
 import { parseAst } from '../parse-ast-index';
 import { bindingifySourcemap, type ExistingRawSourceMap } from '../types/sourcemap';
 import { aggregateBindingErrorsIntoJsError } from '../utils/error';
diff --git a/packages/rolldown/src/plugin/bindingify-output-hooks.ts b/packages/rolldown/src/plugin/bindingify-output-hooks.ts
@@ -1,5 +1,5 @@
 import type { BindingHookFilter, BindingPluginOptions } from '../binding.cjs';
-import { BindingMagicString } from '../binding.cjs';
+import { BindingMagicString } from '../binding-magic-string';
 import { bindingifySourcemap } from '../types/sourcemap';
 import { aggregateBindingErrorsIntoJsError, unwrapBindingResult } from '../utils/error';
 import { normalizeHook } from '../utils/normalize-hook';
diff --git a/packages/rolldown/src/plugin/index.ts b/packages/rolldown/src/plugin/index.ts
@@ -1,10 +1,7 @@
 import type { Program } from '@oxc-project/types';
 import type { InputOptions, OutputOptions } from '..';
-import type {
-  BindingHookResolveIdExtraArgs,
-  BindingMagicString,
-  BindingTransformHookExtraArgs,
-} from '../binding.cjs';
+import type { BindingHookResolveIdExtraArgs, BindingTransformHookExtraArgs } from '../binding.cjs';
+import type { BindingMagicString } from '../binding-magic-string';
 import type { BuiltinPlugin } from '../builtin-plugin/utils';
 import type { DefinedHookNames } from '../constants/plugin';
 import type { DEFINED_HOOK_NAMES } from '../constants/plugin';
diff --git a/packages/rolldown/src/plugin/transform-plugin-context.ts b/packages/rolldown/src/plugin/transform-plugin-context.ts
@@ -1,8 +1,5 @@
-import type {
-  BindingMagicString,
-  BindingPluginContext,
-  BindingTransformPluginContext,
-} from '../binding.cjs';
+import type { BindingPluginContext, BindingTransformPluginContext } from '../binding.cjs';
+import type { BindingMagicString } from '../binding-magic-string';
 import {
   type LoggingFunctionWithPosition,
   type LogHandler,
diff --git a/packages/rolldown/tests/magic-string/magic-string-to-string-tag.test.ts b/packages/rolldown/tests/magic-string/magic-string-to-string-tag.test.ts
@@ -0,0 +1,29 @@
+import assert from 'node:assert';
+import { BindingMagicString as MagicString } from 'rolldown';
+import { describe, it } from 'vitest';
+
+describe('MagicString isRolldownMagicString', () => {
+  it('should have isRolldownMagicString on prototype', () => {
+    assert.strictEqual(MagicString.prototype.isRolldownMagicString, true);
+  });
+
+  it('should be accessible on instances', () => {
+    const s = new MagicString('hello');
+    assert.strictEqual(s.isRolldownMagicString, true);
+  });
+
+  it('should allow detection without importing rolldown', () => {
+    const s = new MagicString('hello');
+    // This is the primary use case: external packages can detect native
+    // BindingMagicString instances using isRolldownMagicString instead of
+    // the fragile `s.constructor.name === 'RolldownMagicString'`
+    const isNative = (obj: unknown): boolean =>
+      typeof obj === 'object' &&
+      obj !== null &&
+      (obj as Record<string, unknown>).isRolldownMagicString === true;
+    assert.ok(isNative(s));
+    assert.ok(!isNative({}));
+    assert.ok(!isNative('string'));
+    assert.ok(!isNative(null));
+  });
+});
