vite-plugin-assets-split 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mr. Python
+
+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,67 @@
+# vite-plugin-assets-split
+
+A Vite plugin to split large static assets into smaller chunks. This is useful for dealing with file size limitations on certain static hosting platforms (e.g., Cloudflare Pages, GitHub Pages limits).
+
+## Features
+
+- Import static files with `?split` query parameter.
+- Automatically splits files into chunks based on a configurable size limit.
+- Returns an array of URLs for the chunks.
+
+## Installation
+
+```bash
+npm install vite-plugin-assets-split -D
+# or
+yarn add vite-plugin-assets-split -D
+# or
+pnpm add vite-plugin-assets-split -D
+```
+
+## Usage
+
+### 1. Configure the plugin in `vite.config.ts`
+
+```typescript
+import { defineConfig } from 'vite';
+import assetsSplit from 'vite-plugin-assets-split';
+
+export default defineConfig({
+  plugins: [
+    assetsSplit({
+      limit: 1024 * 1024 * 2, // Optional: Set chunk size limit (e.g., 2MB). Default is 1MB.
+    }),
+  ],
+});
+```
+
+### 2. Import assets with `?split`
+
+```typescript
+// Import a large file. The result will be an array of strings (URLs).
+import modelChunks from './large-model.glb?split';
+
+console.log(modelChunks); 
+// Output: ['/assets/large-model.part1.glb', '/assets/large-model.part2.glb', ...]
+
+// Example: Loading a split file (pseudo-code)
+async function loadSplitFile(urls: string[]) {
+  const buffers = await Promise.all(urls.map(url => fetch(url).then(res => res.arrayBuffer())));
+  // Combine buffers logic here...
+}
+```
+
+## TypeScript Support
+
+To get proper type inference for imports with `?split`, add the following to your `vite-env.d.ts` or a global declaration file:
+
+```typescript
+declare module '*?split' {
+  const urls: string[];
+  export default urls;
+}
+```
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,12 @@
+import { Plugin } from 'vite';
+
+interface Options {
+    /**
+     * Maximum size of each chunk in bytes.
+     * Default is 1MB (1024 * 1024 bytes).
+     */
+    limit?: number;
+}
+declare function assetsSplit(options?: Options): Plugin;
+
+export { type Options, assetsSplit as default };

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+import { Plugin } from 'vite';
+
+interface Options {
+    /**
+     * Maximum size of each chunk in bytes.
+     * Default is 1MB (1024 * 1024 bytes).
+     */
+    limit?: number;
+}
+declare function assetsSplit(options?: Options): Plugin;
+
+export { type Options, assetsSplit as default };

package/dist/index.js

@@ -0,0 +1,138 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+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 __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  default: () => assetsSplit
+});
+module.exports = __toCommonJS(index_exports);
+var import_promises = __toESM(require("fs/promises"));
+var import_node_path = __toESM(require("path"));
+function assetsSplit(options = {}) {
+  const limit = options.limit ?? 1024 * 1024;
+  let config;
+  return {
+    name: "vite-plugin-assets-split",
+    enforce: "pre",
+    // Ensure this runs before Vite's default asset handling
+    configResolved(resolvedConfig) {
+      config = resolvedConfig;
+    },
+    configureServer(server) {
+      server.middlewares.use(async (req, res, next) => {
+        const urlObj = new URL(req.url, `http://${req.headers.host}`);
+        if (urlObj.searchParams.has("split-chunk")) {
+          try {
+            const chunkIndex = parseInt(urlObj.searchParams.get("split-chunk"), 10);
+            let filePath;
+            const pathname = urlObj.pathname;
+            if (pathname.startsWith("/@fs/")) {
+              filePath = pathname.slice(5);
+            } else {
+              filePath = import_node_path.default.join(config.root, pathname);
+            }
+            filePath = decodeURIComponent(filePath);
+            try {
+              const buffer = await import_promises.default.readFile(filePath);
+              const start = chunkIndex * limit;
+              if (start >= buffer.length) {
+                res.statusCode = 404;
+                res.end("Chunk index out of bounds");
+                return;
+              }
+              const end = Math.min(start + limit, buffer.length);
+              const chunk = buffer.subarray(start, end);
+              res.setHeader("Content-Type", "application/octet-stream");
+              res.setHeader("Content-Length", chunk.length);
+              res.end(chunk);
+            } catch (err) {
+              next(err);
+            }
+          } catch (e) {
+            console.error("[vite-plugin-assets-split] Middleware error:", e);
+            next(e);
+          }
+        } else {
+          next();
+        }
+      });
+    },
+    async load(id) {
+      if (!id.includes("?")) return null;
+      const [filePath, query] = id.split("?");
+      const params = new URLSearchParams(query);
+      if (!params.has("split")) {
+        return null;
+      }
+      try {
+        const buffer = await import_promises.default.readFile(filePath);
+        const totalSize = buffer.length;
+        const chunkCount = Math.ceil(totalSize / limit);
+        const fileName = import_node_path.default.basename(filePath);
+        const ext = import_node_path.default.extname(fileName);
+        const nameWithoutExt = import_node_path.default.basename(fileName, ext);
+        const references = [];
+        if (config.command === "serve") {
+          for (let i = 0; i < chunkCount; i++) {
+            let urlPath;
+            if (filePath.startsWith(config.root)) {
+              urlPath = "/" + import_node_path.default.relative(config.root, filePath);
+            } else {
+              urlPath = "/@fs/" + filePath;
+            }
+            urlPath = urlPath.split(import_node_path.default.sep).join("/");
+            references.push(`${urlPath}?split-chunk=${i}`);
+          }
+          return `export default ${JSON.stringify(references)};`;
+        } else {
+          for (let i = 0; i < chunkCount; i++) {
+            const start = i * limit;
+            const end = Math.min(start + limit, totalSize);
+            const chunk = buffer.subarray(start, end);
+            const refId = this.emitFile({
+              type: "asset",
+              name: `${nameWithoutExt}.part${i + 1}${ext}`,
+              source: chunk
+            });
+            references.push(refId);
+          }
+          const code = `export default [${references.map((ref) => `import.meta.ROLLUP_FILE_URL_${ref}`).join(", ")}];`;
+          return {
+            code,
+            map: null
+          };
+        }
+      } catch (error) {
+        console.error(`[vite-plugin-assets-split] Error processing file ${filePath}:`, error);
+        throw error;
+      }
+    }
+  };
+}

package/dist/index.mjs

@@ -0,0 +1,107 @@
+// src/index.ts
+import fs from "fs/promises";
+import path from "path";
+function assetsSplit(options = {}) {
+  const limit = options.limit ?? 1024 * 1024;
+  let config;
+  return {
+    name: "vite-plugin-assets-split",
+    enforce: "pre",
+    // Ensure this runs before Vite's default asset handling
+    configResolved(resolvedConfig) {
+      config = resolvedConfig;
+    },
+    configureServer(server) {
+      server.middlewares.use(async (req, res, next) => {
+        const urlObj = new URL(req.url, `http://${req.headers.host}`);
+        if (urlObj.searchParams.has("split-chunk")) {
+          try {
+            const chunkIndex = parseInt(urlObj.searchParams.get("split-chunk"), 10);
+            let filePath;
+            const pathname = urlObj.pathname;
+            if (pathname.startsWith("/@fs/")) {
+              filePath = pathname.slice(5);
+            } else {
+              filePath = path.join(config.root, pathname);
+            }
+            filePath = decodeURIComponent(filePath);
+            try {
+              const buffer = await fs.readFile(filePath);
+              const start = chunkIndex * limit;
+              if (start >= buffer.length) {
+                res.statusCode = 404;
+                res.end("Chunk index out of bounds");
+                return;
+              }
+              const end = Math.min(start + limit, buffer.length);
+              const chunk = buffer.subarray(start, end);
+              res.setHeader("Content-Type", "application/octet-stream");
+              res.setHeader("Content-Length", chunk.length);
+              res.end(chunk);
+            } catch (err) {
+              next(err);
+            }
+          } catch (e) {
+            console.error("[vite-plugin-assets-split] Middleware error:", e);
+            next(e);
+          }
+        } else {
+          next();
+        }
+      });
+    },
+    async load(id) {
+      if (!id.includes("?")) return null;
+      const [filePath, query] = id.split("?");
+      const params = new URLSearchParams(query);
+      if (!params.has("split")) {
+        return null;
+      }
+      try {
+        const buffer = await fs.readFile(filePath);
+        const totalSize = buffer.length;
+        const chunkCount = Math.ceil(totalSize / limit);
+        const fileName = path.basename(filePath);
+        const ext = path.extname(fileName);
+        const nameWithoutExt = path.basename(fileName, ext);
+        const references = [];
+        if (config.command === "serve") {
+          for (let i = 0; i < chunkCount; i++) {
+            let urlPath;
+            if (filePath.startsWith(config.root)) {
+              urlPath = "/" + path.relative(config.root, filePath);
+            } else {
+              urlPath = "/@fs/" + filePath;
+            }
+            urlPath = urlPath.split(path.sep).join("/");
+            references.push(`${urlPath}?split-chunk=${i}`);
+          }
+          return `export default ${JSON.stringify(references)};`;
+        } else {
+          for (let i = 0; i < chunkCount; i++) {
+            const start = i * limit;
+            const end = Math.min(start + limit, totalSize);
+            const chunk = buffer.subarray(start, end);
+            const refId = this.emitFile({
+              type: "asset",
+              name: `${nameWithoutExt}.part${i + 1}${ext}`,
+              source: chunk
+            });
+            references.push(refId);
+          }
+          const code = `export default [${references.map((ref) => `import.meta.ROLLUP_FILE_URL_${ref}`).join(", ")}];`;
+          return {
+            code,
+            map: null
+          };
+        }
+      } catch (error) {
+        console.error(`[vite-plugin-assets-split] Error processing file ${filePath}:`, error);
+        throw error;
+      }
+    }
+  };
+}
+export {
+  assetsSplit as default
+};

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "vite-plugin-assets-split",
+  "version": "1.0.0",
+  "description": "A Vite plugin to split large static assets into smaller chunks using a special import query.",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts",
+    "dev": "tsup src/index.ts --format cjs,esm --dts --watch",
+    "playground": "vite playground",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "vite",
+    "plugin",
+    "assets",
+    "split",
+    "chunk",
+    "large file"
+  ],
+  "author": "Mr-Python-in-China",
+  "license": "MIT",
+  "peerDependencies": {
+    "vite": "*"
+  },
+  "devDependencies": {
+    "@types/node": "^25.1.0",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3",
+    "vite": "^7.3.1"
+  }
+}