vite-legacy-pass-through 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 el_jijuna
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,143 @@
+# vite-legacy-pass-through ⚡
+
+> A Vite plugin that marks legacy libraries as external, preventing Rolldown from bundling them and causing CommonJS interop errors at runtime.
+
+---
+
+## 🧩 The story behind this plugin
+
+This plugin was born out of a real-world headache while juggling a legacy component library and a newer one built on top of it.
+
+The setup looked like this:
+
+- 🏛️ **lib-legacy** — an older component library with `prop-types` as a dependency. Used directly inside a Vite-powered web app, everything worked perfectly fine.
+- ✨ **lib-awesome** — a newer library built to override and extend UI and functionality from `lib-legacy`. Its components imported from `lib-legacy`, added behaviour, and re-exported them.
+
+The problem surfaced the moment **lib-awesome** was built with **Vite 8**. Because it imported components from `lib-legacy` and re-exported them, Rolldown pulled `prop-types` deep into the bundle. The output contained a file named something like `prop-types-a1b2c3d4.js` with a bare `require(...)` call — which blew up at runtime in ESM environments:
+
+```
+ReferenceError: require is not defined
+    at prop-types-a1b2c3d4.js:1:1
+```
+
+After a lot of reading about how Vite 8 and Rolldown handle module bundling and CJS/ESM interop, the cleanest escape hatch turned out to be telling Rolldown: *"don't touch lib-legacy — let it pass through as-is."*
+
+That's exactly what this plugin does.
+
+```mermaid
+flowchart TD
+    subgraph without["❌ Without the plugin"]
+        A[lib-awesome] -->|imports & re-exports| B[lib-legacy]
+        B -->|has dependency| C[prop-types CJS]
+        A -->|build| D[Rolldown bundles everything]
+        D --> E["prop-types-a1b2c3d4.js\n⚠️ require() call inside"]
+        E --> F["💥 ReferenceError: require is not defined"]
+    end
+
+    subgraph with["✅ With vite-legacy-pass-through"]
+        G[lib-awesome] -->|imports & re-exports| H[lib-legacy]
+        H -->|has dependency| I[prop-types CJS]
+        G -->|build| J[Rolldown sees lib-legacy as external]
+        J --> K["lib-legacy stays as import statement\n✅ no bundling, no require()"]
+        K --> L["🚀 Works at runtime"]
+    end
+```
+
+> ⚠️ **Important:** Rolldown does **not** recommend marking packages as external this way in library builds. Doing so shifts the module resolution responsibility entirely to the consumer — they must have the library available in their environment. Use this plugin only when you understand that trade-off and the legacy library is guaranteed to be present at runtime.
+
+---
+
+## 📦 Installation
+
+```bash
+npm install -D vite-legacy-pass-through
+```
+
+---
+
+## 🚀 Usage
+
+```ts
+// vite.config.ts
+import { defineConfig } from 'vite'
+import { legacyPassThrough } from 'vite-legacy-pass-through'
+
+export default defineConfig({
+  plugins: [
+    legacyPassThrough({
+      libs: ['lib-legacy'],
+    }),
+  ],
+})
+```
+
+Multiple libraries:
+
+```ts
+legacyPassThrough({
+  libs: ['lib-legacy', 'another-legacy-lib'],
+})
+```
+
+With logging enabled (useful during development to confirm which imports are being bypassed):
+
+```ts
+legacyPassThrough({
+  libs: ['lib-legacy'],
+  showLog: true,
+})
+```
+
+Output when `showLog: true`:
+
+```
+[vite-legacy-pass-through] Resolving: lib-legacy/components/Button
+[vite-legacy-pass-through] Resolving: lib-legacy/utils/format
+```
+
+---
+
+## ⚙️ Options
+
+| Option | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `libs` | `string[]` | Yes | — | List of library names to mark as external. Empty strings are ignored. Must have at least one valid entry. |
+| `showLog` | `boolean` | No | `false` | Logs each resolved import to the console. |
+
+---
+
+## 🔍 How it works
+
+The plugin hooks into Vite's `resolveId` phase with `enforce: 'pre'` — meaning it runs before any other plugin — and marks any import whose path starts with `<lib>/` as external. Rolldown then skips bundling it entirely and leaves the import statement untouched in the output.
+
+```
+import Button from 'lib-legacy/components/Button'
+           ↓  resolveId hook intercepts
+{ id: 'lib-legacy/components/Button', external: true }
+           ↓  Rolldown skips it, output keeps the import
+import Button from 'lib-legacy/components/Button'
+```
+
+> Note: bare imports (`import 'lib-legacy'` without a subpath) are **not** affected — only subpath imports (`lib-legacy/...`) are matched. This is intentional to avoid over-matching.
+
+---
+
+## 🤔 When to use this
+
+- You are building a library that imports and re-exports from a legacy package.
+- That legacy package uses CommonJS internally (e.g. `prop-types`, older UI kits).
+- Vite 8 / Rolldown is wrapping those CJS modules into the bundle and generating `require()` calls that break in ESM environments.
+- The legacy package will be available at runtime in the consumer's environment (i.e. it is a peer or runtime dependency, not something you need to ship inside your bundle).
+
+---
+
+## 📋 Requirements
+
+- **Vite**: `^8.0.0`
+- **Node.js**: `>=18`
+
+---
+
+## 📄 License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,52 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  default: () => index_default,
+  legacyPassThrough: () => legacyPassThrough
+});
+module.exports = __toCommonJS(index_exports);
+function legacyPassThrough({ libs, showLog } = { libs: [] }) {
+  const validLibs = libs.filter((lib) => lib.trim() !== "");
+  if (!validLibs.length) {
+    throw new Error('The "libs" option must be a non-empty array for the legacyPassThrough plugin.');
+  }
+  const prefixes = validLibs.map((lib) => `${lib}/`);
+  return {
+    name: "vite-legacy-pass-through",
+    enforce: "pre",
+    resolveId(source) {
+      if (prefixes.some((prefix) => source.startsWith(prefix))) {
+        if (showLog) {
+          console.log(`[vite-legacy-pass-through] Resolving: ${source}`);
+        }
+        return { id: source, external: true };
+      }
+      return null;
+    }
+  };
+}
+var index_default = legacyPassThrough;
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  legacyPassThrough
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["import type { Plugin } from 'vite'\n\nexport interface LegacyPassThroughOptions {\n  libs: string[]\n  showLog?: boolean\n}\n\nexport function legacyPassThrough({ libs, showLog }: LegacyPassThroughOptions = { libs: [] }): Plugin {\n  const validLibs = libs.filter(lib => lib.trim() !== '')\n\n  if (!validLibs.length) {\n    throw new Error('The \"libs\" option must be a non-empty array for the legacyPassThrough plugin.')\n  }\n\n  const prefixes = validLibs.map(lib => `${lib}/`)\n\n  return {\n    name: 'vite-legacy-pass-through',\n    enforce: 'pre',\n    resolveId(source) {\n      if (prefixes.some(prefix => source.startsWith(prefix))) {\n        if (showLog) {\n          console.log(`[vite-legacy-pass-through] Resolving: ${source}`)\n        }\n        return { id: source, external: true }\n      }\n      return null\n    },\n  }\n}\n\nexport default legacyPassThrough\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAOO,SAAS,kBAAkB,EAAE,MAAM,QAAQ,IAA8B,EAAE,MAAM,CAAC,EAAE,GAAW;AACpG,QAAM,YAAY,KAAK,OAAO,SAAO,IAAI,KAAK,MAAM,EAAE;AAEtD,MAAI,CAAC,UAAU,QAAQ;AACrB,UAAM,IAAI,MAAM,+EAA+E;AAAA,EACjG;AAEA,QAAM,WAAW,UAAU,IAAI,SAAO,GAAG,GAAG,GAAG;AAE/C,SAAO;AAAA,IACL,MAAM;AAAA,IACN,SAAS;AAAA,IACT,UAAU,QAAQ;AAChB,UAAI,SAAS,KAAK,YAAU,OAAO,WAAW,MAAM,CAAC,GAAG;AACtD,YAAI,SAAS;AACX,kBAAQ,IAAI,yCAAyC,MAAM,EAAE;AAAA,QAC/D;AACA,eAAO,EAAE,IAAI,QAAQ,UAAU,KAAK;AAAA,MACtC;AACA,aAAO;AAAA,IACT;AAAA,EACF;AACF;AAEA,IAAO,gBAAQ;","names":[]}

package/dist/index.d.cts

@@ -0,0 +1,9 @@
+import { Plugin } from 'vite';
+
+interface LegacyPassThroughOptions {
+    libs: string[];
+    showLog?: boolean;
+}
+declare function legacyPassThrough({ libs, showLog }?: LegacyPassThroughOptions): Plugin;
+
+export { type LegacyPassThroughOptions, legacyPassThrough as default, legacyPassThrough };

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+import { Plugin } from 'vite';
+
+interface LegacyPassThroughOptions {
+    libs: string[];
+    showLog?: boolean;
+}
+declare function legacyPassThrough({ libs, showLog }?: LegacyPassThroughOptions): Plugin;
+
+export { type LegacyPassThroughOptions, legacyPassThrough as default, legacyPassThrough };

package/dist/index.js

@@ -0,0 +1,27 @@
+// src/index.ts
+function legacyPassThrough({ libs, showLog } = { libs: [] }) {
+  const validLibs = libs.filter((lib) => lib.trim() !== "");
+  if (!validLibs.length) {
+    throw new Error('The "libs" option must be a non-empty array for the legacyPassThrough plugin.');
+  }
+  const prefixes = validLibs.map((lib) => `${lib}/`);
+  return {
+    name: "vite-legacy-pass-through",
+    enforce: "pre",
+    resolveId(source) {
+      if (prefixes.some((prefix) => source.startsWith(prefix))) {
+        if (showLog) {
+          console.log(`[vite-legacy-pass-through] Resolving: ${source}`);
+        }
+        return { id: source, external: true };
+      }
+      return null;
+    }
+  };
+}
+var index_default = legacyPassThrough;
+export {
+  index_default as default,
+  legacyPassThrough
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["import type { Plugin } from 'vite'\n\nexport interface LegacyPassThroughOptions {\n  libs: string[]\n  showLog?: boolean\n}\n\nexport function legacyPassThrough({ libs, showLog }: LegacyPassThroughOptions = { libs: [] }): Plugin {\n  const validLibs = libs.filter(lib => lib.trim() !== '')\n\n  if (!validLibs.length) {\n    throw new Error('The \"libs\" option must be a non-empty array for the legacyPassThrough plugin.')\n  }\n\n  const prefixes = validLibs.map(lib => `${lib}/`)\n\n  return {\n    name: 'vite-legacy-pass-through',\n    enforce: 'pre',\n    resolveId(source) {\n      if (prefixes.some(prefix => source.startsWith(prefix))) {\n        if (showLog) {\n          console.log(`[vite-legacy-pass-through] Resolving: ${source}`)\n        }\n        return { id: source, external: true }\n      }\n      return null\n    },\n  }\n}\n\nexport default legacyPassThrough\n"],"mappings":";AAOO,SAAS,kBAAkB,EAAE,MAAM,QAAQ,IAA8B,EAAE,MAAM,CAAC,EAAE,GAAW;AACpG,QAAM,YAAY,KAAK,OAAO,SAAO,IAAI,KAAK,MAAM,EAAE;AAEtD,MAAI,CAAC,UAAU,QAAQ;AACrB,UAAM,IAAI,MAAM,+EAA+E;AAAA,EACjG;AAEA,QAAM,WAAW,UAAU,IAAI,SAAO,GAAG,GAAG,GAAG;AAE/C,SAAO;AAAA,IACL,MAAM;AAAA,IACN,SAAS;AAAA,IACT,UAAU,QAAQ;AAChB,UAAI,SAAS,KAAK,YAAU,OAAO,WAAW,MAAM,CAAC,GAAG;AACtD,YAAI,SAAS;AACX,kBAAQ,IAAI,yCAAyC,MAAM,EAAE;AAAA,QAC/D;AACA,eAAO,EAAE,IAAI,QAAQ,UAAU,KAAK;AAAA,MACtC;AACA,aAAO;AAAA,IACT;AAAA,EACF;AACF;AAEA,IAAO,gBAAQ;","names":[]}

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "vite-legacy-pass-through",
+  "version": "1.0.0",
+  "description": "Vite plugin to pass through legacy assets without transformation",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "vite",
+    "plugin",
+    "legacy",
+    "pass-through",
+    "rolldown",
+    "external",
+    "prop-types"
+  ],
+  "author": "el_jijuna",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/el_jijuna/vite-legacy-pass-through.git"
+  },
+  "bugs": {
+    "url": "https://github.com/el_jijuna/vite-legacy-pass-through/issues"
+  },
+  "homepage": "https://github.com/el_jijuna/vite-legacy-pass-through#readme",
+  "engines": {
+    "node": ">=18"
+  },
+  "peerDependencies": {
+    "vite": "^8.0.0"
+  },
+  "devDependencies": {
+    "tsup": "^8.4.0",
+    "typescript": "^5.8.3",
+    "vite": "^8.0.3",
+    "vitest": "^4.1.2"
+  }
+}