fix(core): resolve Rolldown bindings via platform packages

.github/workflows/release.yml

@@ -158,6 +158,21 @@ jobs:
       - name: Prepare and publish native addons
         run: node ./packages/cli/publish-native-addons.ts --mode npm
 
+      - name: Pin core native optional dependencies
+        run: |
+          node --input-type=module <<'EOF'
+          import { readFile, writeFile } from 'node:fs/promises';
+
+          const file = 'packages/core/package.json';
+          const pkg = JSON.parse(await readFile(file, 'utf8'));
+          for (const name of Object.keys(pkg.optionalDependencies ?? {})) {
+            if (name.startsWith('@voidzero-dev/vite-plus-')) {
+              pkg.optionalDependencies[name] = process.env.VERSION;
+            }
+          }
+          await writeFile(file, `${JSON.stringify(pkg, null, 2)}\n`);
+          EOF
+
       - name: Publish
         run: |
           pnpm publish --filter=./packages/core --tag latest --access public --no-git-checks

packages/cli/BUNDLING.md

@@ -154,14 +154,16 @@ packages/cli/
 
 The CLI builds native bindings for the following platform targets:
 
-| Target                      | Platform | Architecture | Output File                       |
-| --------------------------- | -------- | ------------ | --------------------------------- |
-| `aarch64-apple-darwin`      | macOS    | ARM64        | `vite-plus.darwin-arm64.node`     |
-| `x86_64-apple-darwin`       | macOS    | x64          | `vite-plus.darwin-x64.node`       |
-| `aarch64-unknown-linux-gnu` | Linux    | ARM64        | `vite-plus.linux-arm64-gnu.node`  |
-| `x86_64-unknown-linux-gnu`  | Linux    | x64          | `vite-plus.linux-x64-gnu.node`    |
-| `aarch64-pc-windows-msvc`   | Windows  | ARM64        | `vite-plus.win32-arm64-msvc.node` |
-| `x86_64-pc-windows-msvc`    | Windows  | x64          | `vite-plus.win32-x64-msvc.node`   |
+| Target                       | Platform | Architecture | Output File                       |
+| ---------------------------- | -------- | ------------ | --------------------------------- |
+| `aarch64-apple-darwin`       | macOS    | ARM64        | `vite-plus.darwin-arm64.node`     |
+| `x86_64-apple-darwin`        | macOS    | x64          | `vite-plus.darwin-x64.node`       |
+| `aarch64-unknown-linux-gnu`  | Linux    | ARM64        | `vite-plus.linux-arm64-gnu.node`  |
+| `aarch64-unknown-linux-musl` | Linux    | ARM64        | `vite-plus.linux-arm64-musl.node` |
+| `x86_64-unknown-linux-gnu`   | Linux    | x64          | `vite-plus.linux-x64-gnu.node`    |
+| `x86_64-unknown-linux-musl`  | Linux    | x64          | `vite-plus.linux-x64-musl.node`   |
+| `aarch64-pc-windows-msvc`    | Windows  | ARM64        | `vite-plus.win32-arm64-msvc.node` |
+| `x86_64-pc-windows-msvc`     | Windows  | x64          | `vite-plus.win32-x64-msvc.node`   |
 
 These targets are defined in `package.json` under the `napi.targets` field.
 
@@ -220,29 +222,29 @@ await cli.build({
 
 ### Module Specifier Rewriting
 
-During release builds, the core package rewrites all `@rolldown/binding-*` imports to point to `vite-plus/binding`:
+During release builds, the core package rewrites each `@rolldown/binding-*` import to the matching Vite+ platform package:
 
 ```typescript
 // In packages/core/build.ts
 if (process.env.RELEASE_BUILD) {
-  // @rolldown/binding-darwin-arm64 → vite-plus/binding
-  source = source.replace(/@rolldown\/binding-([a-z0-9-]+)/g, 'vite-plus/binding');
+  source = source.replace(/@rolldown\/binding-([a-z0-9-]+)/g, '@voidzero-dev/vite-plus-$1');
 }
 ```
 
 **Transformation examples**:
 
-| Original Import                    | After Rewrite       |
-| ---------------------------------- | ------------------- |
-| `@rolldown/binding-darwin-arm64`   | `vite-plus/binding` |
-| `@rolldown/binding-linux-x64-gnu`  | `vite-plus/binding` |
-| `@rolldown/binding-win32-x64-msvc` | `vite-plus/binding` |
+| Original Import                    | After Rewrite                            |
+| ---------------------------------- | ---------------------------------------- |
+| `@rolldown/binding-darwin-arm64`   | `@voidzero-dev/vite-plus-darwin-arm64`   |
+| `@rolldown/binding-linux-x64-gnu`  | `@voidzero-dev/vite-plus-linux-x64-gnu`  |
+| `@rolldown/binding-win32-x64-msvc` | `@voidzero-dev/vite-plus-win32-x64-msvc` |
 
 This means:
 
-1. The bundled rolldown code in `@voidzero-dev/vite-plus-core/rolldown` resolves native bindings from `vite-plus/binding`
+1. The bundled rolldown code in `@voidzero-dev/vite-plus-core/rolldown` resolves native bindings from core's declared optional platform dependencies
 2. Users don't need to install separate `@rolldown/binding-*` platform packages
-3. The single `.node` file contains both vite-plus task runner and rolldown bindings
+3. The platform `.node` file contains both vite-plus task runner and rolldown bindings
+4. The `vite-plus/binding` export remains available as a compatibility entrypoint for direct consumers
 
 ### Native Binding Contents
 
@@ -259,23 +261,28 @@ When compiled with `RELEASE_BUILD=1`, the `.node` file contains:
 User imports 'vite-plus/rolldown'
   → packages/cli re-exports from @voidzero-dev/vite-plus-core/rolldown
     → packages/core/dist/rolldown/index.mjs
-      → Native binding: vite-plus/binding (rewritten from @rolldown/binding-*)
-        → binding/vite-plus.darwin-arm64.node (contains rolldown_binding)
+      → Native binding: @voidzero-dev/vite-plus-darwin-arm64
+        → vite-plus.darwin-arm64.node (contains rolldown_binding)
 ```
 
+`vite-plus/binding` still exists for compatibility and uses the same platform packages under the CLI package's public export.
+
 ### Platform-Specific Publishing
 
 Native bindings are published as separate platform packages for optimal install size:
 
-| Platform    | Published Package                         |
-| ----------- | ----------------------------------------- |
-| macOS ARM64 | `@voidzero-dev/vite-plus-darwin-arm64`    |
-| macOS x64   | `@voidzero-dev/vite-plus-darwin-x64`      |
-| Linux ARM64 | `@voidzero-dev/vite-plus-linux-arm64-gnu` |
-| Linux x64   | `@voidzero-dev/vite-plus-linux-x64-gnu`   |
-| Windows x64 | `@voidzero-dev/vite-plus-win32-x64-msvc`  |
-
-These are automatically installed via `optionalDependencies` based on the user's platform.
+| Platform          | Published Package                          |
+| ----------------- | ------------------------------------------ |
+| macOS ARM64       | `@voidzero-dev/vite-plus-darwin-arm64`     |
+| macOS x64         | `@voidzero-dev/vite-plus-darwin-x64`       |
+| Linux ARM64 glibc | `@voidzero-dev/vite-plus-linux-arm64-gnu`  |
+| Linux ARM64 musl  | `@voidzero-dev/vite-plus-linux-arm64-musl` |
+| Linux x64 glibc   | `@voidzero-dev/vite-plus-linux-x64-gnu`    |
+| Linux x64 musl    | `@voidzero-dev/vite-plus-linux-x64-musl`   |
+| Windows ARM64     | `@voidzero-dev/vite-plus-win32-arm64-msvc` |
+| Windows x64       | `@voidzero-dev/vite-plus-win32-x64-msvc`   |
+
+These are automatically installed via `optionalDependencies` based on the user's platform. The CLI and core packages both declare the platform packages they may load.
 
 See `publish-native-addons.ts` for the publishing pipeline.
 

packages/core/BUNDLING.md

@@ -43,7 +43,7 @@ await cp(join(rolldownPluginUtilsDir, 'dist'), join(projectDir, 'dist', 'pluginu
 
 - `@rolldown/pluginutils` → `@voidzero-dev/vite-plus-core/rolldown/pluginutils`
 - `rolldown/*` → `@voidzero-dev/vite-plus-core/rolldown/*`
-- In release builds: `@rolldown/binding-*` → `vite-plus/binding`
+- In release builds: `@rolldown/binding-*` → `@voidzero-dev/vite-plus-*`
 
 **Input**: `rolldown/packages/rolldown/dist/`
 **Output**: `dist/rolldown/`
@@ -96,6 +96,7 @@ This is the most complex step, using the upstream `vite-rolldown.config` with mo
 - `peerDependencies` - Merged from tsdown and vite
 - `peerDependenciesMeta` - Merged from tsdown and vite
 - `bundledVersions` - Records vite, rolldown, and tsdown versions
+- `optionalDependencies` - Adds the Vite+ native platform packages that release-built Rolldown may load
 
 ---
 
@@ -147,40 +148,45 @@ During release builds (`RELEASE_BUILD=1`), an additional critical transformation
 ```typescript
 // In bundleRolldown()
 if (process.env.RELEASE_BUILD) {
-  // @rolldown/binding-darwin-arm64 → vite-plus/binding
-  source = source.replace(/@rolldown\/binding-([a-z0-9-]+)/g, 'vite-plus/binding');
+  source = source.replace(/@rolldown\/binding-([a-z0-9-]+)/g, '@voidzero-dev/vite-plus-$1');
   // Sync version strings
   source = source.replaceAll(`${rolldownBindingVersion}`, pkgJson.version);
 }
 ```
 
 **Platform-specific binding rewrites**:
 
-| Original Import                     | Rewritten Import    |
-| ----------------------------------- | ------------------- |
-| `@rolldown/binding-darwin-arm64`    | `vite-plus/binding` |
-| `@rolldown/binding-darwin-x64`      | `vite-plus/binding` |
-| `@rolldown/binding-linux-arm64-gnu` | `vite-plus/binding` |
-| `@rolldown/binding-linux-x64-gnu`   | `vite-plus/binding` |
-| `@rolldown/binding-win32-x64-msvc`  | `vite-plus/binding` |
+| Original Import                      | Rewritten Import                           |
+| ------------------------------------ | ------------------------------------------ |
+| `@rolldown/binding-darwin-arm64`     | `@voidzero-dev/vite-plus-darwin-arm64`     |
+| `@rolldown/binding-darwin-x64`       | `@voidzero-dev/vite-plus-darwin-x64`       |
+| `@rolldown/binding-linux-arm64-gnu`  | `@voidzero-dev/vite-plus-linux-arm64-gnu`  |
+| `@rolldown/binding-linux-arm64-musl` | `@voidzero-dev/vite-plus-linux-arm64-musl` |
+| `@rolldown/binding-linux-x64-gnu`    | `@voidzero-dev/vite-plus-linux-x64-gnu`    |
+| `@rolldown/binding-linux-x64-musl`   | `@voidzero-dev/vite-plus-linux-x64-musl`   |
+| `@rolldown/binding-win32-arm64-msvc` | `@voidzero-dev/vite-plus-win32-arm64-msvc` |
+| `@rolldown/binding-win32-x64-msvc`   | `@voidzero-dev/vite-plus-win32-x64-msvc`   |
 
 **Why this matters**:
 
 1. **Self-contained distribution** - Users don't need to install separate `@rolldown/binding-*` packages
-2. **Version alignment** - The rolldown binding version is synced to the vite-plus version
-3. **Single native module** - The `vite-plus/binding` export points to the CLI's compiled `.node` file which includes `rolldown_binding` when built with `RELEASE_BUILD=1`
+2. **Declared dependency graph** - Core declares the Vite+ platform packages it may load, so pnpm global virtual store and Yarn PnP do not depend on hidden hoisting
+3. **Version alignment** - The rolldown binding version is synced to the vite-plus version
+4. **Compatibility** - `vite-plus/binding` remains exported by the CLI package for direct consumers
 
 **Resolution chain**:
 
 ```
 User code imports '@voidzero-dev/vite-plus-core/rolldown'
   → dist/rolldown/index.mjs
-    → imports 'vite-plus/binding' (rewritten from @rolldown/binding-*)
-      → vite-plus CLI package ./binding export
-        → binding/vite-plus.darwin-arm64.node (contains rolldown_binding)
+    → imports '@voidzero-dev/vite-plus-<platform>'
+      (rewritten from '@rolldown/binding-<platform>')
+      → vite-plus.<platform>.node (contains rolldown_binding)
 ```
 
-See [CLI Package Bundling](../cli/BUNDLING.md#rolldown-native-binding-integration) for details on how the CLI compiles rolldown bindings.
+For example, `darwin-arm64`, `linux-x64-gnu`, and `win32-x64-msvc` resolve through their matching `@voidzero-dev/vite-plus-*` platform packages.
+
+See [CLI Package Bundling](../cli/BUNDLING.md#rolldown-native-binding-integration) for details on how the CLI compiles and publishes the platform packages. The CLI's `vite-plus/binding` export uses the same platform packages as a compatibility entrypoint.
 
 ---
 
@@ -350,7 +356,7 @@ dist/
 # Build the core package
 pnpm -C packages/core build
 
-# Release build (rewrites @rolldown/binding-* to vite-plus/binding)
+# Release build (rewrites @rolldown/binding-* to @voidzero-dev/vite-plus-*)
 RELEASE_BUILD=1 pnpm -C packages/core build
 ```
 

packages/core/__tests__/build-artifacts.spec.ts

@@ -4,6 +4,13 @@ import url from 'node:url';
 
 import { describe, expect, it } from 'vitest';
 
+import cliPkgJson from '../../cli/package.json' with { type: 'json' };
+import {
+  getNativePlatformPackageName,
+  getNativePlatformPackageNames,
+} from '../build-support/native-platform-packages.ts';
+import corePkgJson from '../package.json' with { type: 'json' };
+
 const coreDir = path.resolve(path.dirname(url.fileURLToPath(import.meta.url)), '..');
 const distDir = path.join(coreDir, 'dist');
 
@@ -25,4 +32,37 @@ describe('build artifacts', () => {
     expect(content).toContain('ImportMeta');
     expect(content).toContain('glob');
   });
+
+  it('maps CLI NAPI targets to Vite+ native platform packages', () => {
+    expect(getNativePlatformPackageNames(cliPkgJson.napi.targets)).toEqual([
+      '@voidzero-dev/vite-plus-darwin-arm64',
+      '@voidzero-dev/vite-plus-darwin-x64',
+      '@voidzero-dev/vite-plus-linux-arm64-gnu',
+      '@voidzero-dev/vite-plus-linux-arm64-musl',
+      '@voidzero-dev/vite-plus-linux-x64-gnu',
+      '@voidzero-dev/vite-plus-linux-x64-musl',
+      '@voidzero-dev/vite-plus-win32-x64-msvc',
+      '@voidzero-dev/vite-plus-win32-arm64-msvc',
+    ]);
+  });
+
+  it('declares only generated Vite+ native packages as core optional dependencies', () => {
+    const packageNames = getNativePlatformPackageNames(cliPkgJson.napi.targets);
+    const nativeOptionalDependencyNames = Object.keys(corePkgJson.optionalDependencies).filter(
+      (name) => name.startsWith('@voidzero-dev/vite-plus-'),
+    );
+
+    expect(nativeOptionalDependencyNames.toSorted()).toEqual(packageNames.toSorted());
+    for (const packageName of packageNames) {
+      expect(corePkgJson.optionalDependencies).toHaveProperty(packageName, corePkgJson.version);
+    }
+
+    expect(corePkgJson.peerDependencies).not.toHaveProperty('vite-plus');
+  });
+
+  it('rejects unsupported NAPI targets', () => {
+    expect(() => getNativePlatformPackageName('wasm32-unknown-unknown')).toThrow(
+      'Unsupported NAPI target architecture',
+    );
+  });
 });

packages/core/build-support/native-platform-packages.ts

@@ -0,0 +1,33 @@
+const archMap: Record<string, string> = {
+  aarch64: 'arm64',
+  x86_64: 'x64',
+};
+
+export function getNativePlatformPackageName(target: string): string {
+  const [archTarget, ...platformParts] = target.split('-');
+  const arch = archMap[archTarget];
+  const platform = platformParts.join('-');
+
+  if (!arch) {
+    throw new Error(`Unsupported NAPI target architecture: ${target}`);
+  }
+
+  if (platform === 'apple-darwin') {
+    return `@voidzero-dev/vite-plus-darwin-${arch}`;
+  }
+  if (platform === 'unknown-linux-gnu') {
+    return `@voidzero-dev/vite-plus-linux-${arch}-gnu`;
+  }
+  if (platform === 'unknown-linux-musl') {
+    return `@voidzero-dev/vite-plus-linux-${arch}-musl`;
+  }
+  if (platform === 'pc-windows-msvc') {
+    return `@voidzero-dev/vite-plus-win32-${arch}-msvc`;
+  }
+
+  throw new Error(`Unsupported NAPI target platform: ${target}`);
+}
+
+export function getNativePlatformPackageNames(targets: string[]): string[] {
+  return targets.map(getNativePlatformPackageName);
+}

packages/core/build.ts

@@ -18,8 +18,10 @@ import { glob } from 'tinyglobby';
 
 import { generateLicenseFile } from '../../scripts/generate-license.js';
 import viteRolldownConfig from '../../vite/packages/vite/rolldown.config.js';
+import cliPkgJson from '../cli/package.json' with { type: 'json' };
 import { buildCjsDeps } from './build-support/build-cjs-deps.js';
 import { replaceThirdPartyCjsRequires } from './build-support/find-create-require.js';
+import { getNativePlatformPackageName } from './build-support/native-platform-packages.js';
 import { RewriteImportsPlugin } from './build-support/rewrite-imports.js';
 import {
   createRolldownRewriteRules,
@@ -370,6 +372,8 @@ async function bundleRolldown() {
     },
   });
 
+  const vitePlusNativePackages = new Set(cliPkgJson.napi.targets.map(getNativePlatformPackageName));
+
   // Rewrite @rolldown/pluginutils imports in JS and type declaration files
   for (const file of rolldownFiles) {
     if (
@@ -386,9 +390,23 @@ async function bundleRolldown() {
             with: { type: 'json' },
           })
         ).default.version;
-        // @rolldown/binding-darwin-arm64 → @voidzero-dev/vite-plus-darwin-arm64/binding
-        source = source.replace(/@rolldown\/binding-([a-z0-9-]+)/g, 'vite-plus/binding');
-        source = source.replaceAll(`${rolldownBindingVersion}`, pkgJson.version);
+        source = source.replace(/@rolldown\/binding-([a-z0-9-]+)/g, (specifier, suffix) => {
+          const packageName = `@voidzero-dev/vite-plus-${suffix}`;
+          return vitePlusNativePackages.has(packageName) ? packageName : specifier;
+        });
+        source = source
+          .replaceAll(
+            `bindingPackageVersion !== "${rolldownBindingVersion}"`,
+            `bindingPackageVersion !== "${pkgJson.version}"`,
+          )
+          .replaceAll(
+            `bindingPackageVersion !== '${rolldownBindingVersion}'`,
+            `bindingPackageVersion !== '${pkgJson.version}'`,
+          )
+          .replaceAll(
+            `expected ${rolldownBindingVersion} but got`,
+            `expected ${pkgJson.version} but got`,
+          );
       }
       const newSource = rewriteModuleSpecifiers(source, file, { rules });
       await writeFile(file, newSource);
@@ -794,6 +812,11 @@ async function mergePackageJson() {
     tsdown: tsdownPkg.version,
   };
 
+  destPkg.optionalDependencies = { ...destPkg.optionalDependencies };
+  for (const target of cliPkgJson.napi.targets) {
+    destPkg.optionalDependencies[getNativePlatformPackageName(target)] = destPkg.version;
+  }
+
   const { code, errors } = await format(destPkgPath, JSON.stringify(destPkg, null, 2) + '\n', {
     sortPackageJson: true,
   });

packages/core/package.json

@@ -208,6 +208,14 @@
     }
   },
   "optionalDependencies": {
+    "@voidzero-dev/vite-plus-darwin-arm64": "0.2.2",
+    "@voidzero-dev/vite-plus-darwin-x64": "0.2.2",
+    "@voidzero-dev/vite-plus-linux-arm64-gnu": "0.2.2",
+    "@voidzero-dev/vite-plus-linux-arm64-musl": "0.2.2",
+    "@voidzero-dev/vite-plus-linux-x64-gnu": "0.2.2",
+    "@voidzero-dev/vite-plus-linux-x64-musl": "0.2.2",
+    "@voidzero-dev/vite-plus-win32-arm64-msvc": "0.2.2",
+    "@voidzero-dev/vite-plus-win32-x64-msvc": "0.2.2",
     "fsevents": "~2.3.3"
   },
   "engines": {