vite-plugin-cross-origin-storage 1.0.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,67 @@
+# vite-plugin-cross-origin-storage
+
+A Vite plugin to cache and load static assets (chunks) using the [Cross-Origin Storage (COS) API](https://github.com/WICG/cross-origin-storage).
+
+This plugin progressively enhances your application by attempting to load vendor chunks and other assets from a shared Cross-Origin Storage, reducing bandwidth usage and improving load times across different sites that share common dependencies.
+
+## Features
+
+- **Automatic Import Rewriting**: Rewrites static imports to use COS-loaded Blob URLs when available.
+- **Network Fallback**: Gracefully falls back to standard network requests if COS is unavailable or the asset is missing.
+- **Smart Caching**: Automatically stores fetched assets into COS for future use.
+- **Configurable**: Easily include or exclude specific chunks using glob patterns.
+- **Runtime Loader**: Injects a lightweight loader to handle COS interactions transparently.
+
+## Installation
+
+```bash
+npm install vite-plugin-cross-origin-storage --save-dev
+```
+
+## Usage
+
+Add the plugin to your `vite.config.ts` (or `vite.config.js`):
+
+```ts
+import { defineConfig } from 'vite';
+import cosPlugin from 'vite-plugin-cross-origin-storage';
+
+export default defineConfig({
+  plugins: [
+    cosPlugin({
+      // Configuration options
+      include: ['**/vendor-*'], // Example: only manage vendor chunks
+    }),
+  ],
+});
+```
+
+## Configuration
+
+| Option | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `include` | `string \| RegExp \| Array` | `['**/*']` | Pattern to include chunks to be managed by COS. |
+| `exclude` | `string \| RegExp \| Array` | `undefined` | Pattern to exclude chunks from being managed. |
+
+## How It Works
+
+1. **Build Time**:
+   - The plugin analyzes your bundle and identifies chunks matching the `include` pattern.
+   - It generates a stable hash for each managed chunk.
+   - It rewrites imports in your code to look for a global variable (e.g., `window.__COS_CHUNK_...`) containing the Blob URL of the chunk, falling back to the relative network path if the variable is unset.
+   - It disables the default `<script type="module" src="...">` entry point in your `index.html` and injects a custom `loader.js`.
+
+2. **Runtime**:
+   - The injected loader checks for `navigator.crossOriginStorage`.
+   - If supported, it requests the file handle for each managed chunk using its hash.
+   - **Cache Hit**: If found, it creates a Blob URL and assigns it to the corresponding global variable.
+   - **Cache Miss**: If not found, it fetches the file from the network, stores it in COS, and then creates the Blob URL.
+   - Finally, the loader imports your application's entry point, which now seamlessly uses the cached assets.
+
+## Requirements
+
+- A browser with `Cross-Origin Storage` support (or a [browser extension](https://chromewebstore.google.com/detail/cross-origin-storage/denpnpcgjgikjpoglpjefakmdcbmlgih)).
+
+## License
+
+Apache 2.0

package/index.ts

@@ -0,0 +1,202 @@
+import type { Plugin } from 'vite';
+import crypto from 'crypto';
+import path from 'path';
+import fs from 'fs';
+import { fileURLToPath } from 'url';
+import { createFilter } from '@rollup/pluginutils';
+
+export interface CosPluginOptions {
+  /**
+   * Pattern to include chunks to be managed by COS.
+   * Matches against the output filename (e.g. `assets/vendor-*.js`).
+   * Default: `['**\/*']` (all chunks, except the entry implementation detail)
+   */
+  include?: string | RegExp | (string | RegExp)[];
+
+  /**
+   * Pattern to exclude chunks from being managed by COS.
+   */
+  exclude?: string | RegExp | (string | RegExp)[];
+}
+
+export default function cosPlugin(options: CosPluginOptions = {}): Plugin {
+  const filter = createFilter(options.include || ['**/*'], options.exclude);
+
+  // Resolve loader path relative to this file
+  const __dirname = path.dirname(fileURLToPath(import.meta.url));
+  const loaderPath = path.resolve(__dirname, 'loader.js');
+
+  return {
+    name: 'vite-plugin-cos',
+    apply: 'build',
+    enforce: 'post',
+
+    transformIndexHtml: {
+      order: 'post',
+      handler(html) {
+        // Disable standard entry script to let the COS loader handle it
+        return html.replace(
+          /<script\s+[^>]*type=["']module["'][^>]*src=["'][^"']*index[^"']*["'][^>]*><\/script>/gi,
+          '<!-- Entry script disabled by COS Plugin -->'
+        );
+      }
+    },
+
+    async generateBundle(_options, bundle) {
+      const managedChunks: Record<string, any> = {};
+      let mainChunk: any = null;
+      let htmlAsset: any = null;
+
+      for (const fileName in bundle) {
+        const chunk = bundle[fileName];
+        if (chunk.type === 'chunk') {
+          if (chunk.isEntry) {
+            mainChunk = chunk;
+          } else {
+            // Apply filter to determine if this chunk should be managed by COS
+            if (filter(fileName)) {
+              managedChunks[fileName] = chunk;
+            }
+          }
+        }
+        if (fileName === 'index.html' && chunk.type === 'asset') {
+          htmlAsset = chunk;
+        }
+      }
+
+      if (mainChunk) {
+        // Step 1: Assign stable global variables to managed chunks
+        // We do this BEFORE calculating hashes because the global variable names
+        // are needed for import rewriting, which changes the code, which changes the hash.
+        const chunkInfo: Record<string, { globalVar: string, chunk: any }> = {};
+
+        for (const fileName in managedChunks) {
+          // We use a hash of the filename to ensure it's a valid JS identifier and relatively short
+          // detailed: using filename hash creates a stable identifier for the lifetime of the file path
+          const nameHash = crypto.createHash('sha256').update(fileName).digest('hex').substring(0, 8);
+          chunkInfo[fileName] = {
+            globalVar: `__COS_CHUNK_${nameHash}__`,
+            chunk: managedChunks[fileName]
+          };
+        }
+
+        // Collect ALL chunks to rewrite imports in them
+        const allChunks = Object.values(bundle).filter(c => c.type === 'chunk');
+
+        // Step 2: Rewrite imports TO managed chunks in ALL chunks
+        // This modifies the importers to look for the global variable (Blob URL)
+        for (const targetChunk of allChunks) {
+          for (const fileName in chunkInfo) {
+            // Avoid self-reference
+            if (targetChunk.fileName === fileName) continue;
+
+            const { globalVar } = chunkInfo[fileName];
+            const chunkBasename = fileName.split('/').pop()!;
+            const escapedName = chunkBasename.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+            // Regex to find static imports of the managed chunk
+            const pattern = `import\\s*\\{([^}]+)\\}\\s*from\\s*['"]\\.\\/${escapedName}['"];?`;
+            const importRegex = new RegExp(pattern, 'g');
+
+            if (importRegex.test(targetChunk.code)) {
+              // Calculate relative path for fallback (in case COS loading fails or is unavailable)
+              // targetChunk.fileName is the importer (e.g. "assets/index.js")
+              // fileName is the importee (e.g. "assets/vendor.js")
+              // We need "./vendor.js", not "./assets/vendor.js"
+              let relativePath = path.relative(path.dirname(targetChunk.fileName), fileName);
+              if (!relativePath.startsWith('.')) {
+                relativePath = `./${relativePath}`;
+              }
+
+              targetChunk.code = targetChunk.code.replace(importRegex, (_match: string, bindings: string) => {
+                const destructuringPattern = bindings.split(',').map(b => {
+                  const parts = b.trim().split(/\s+as\s+/);
+                  return parts.length === 2 ? `${parts[0]}:${parts[1]}` : parts[0];
+                }).join(',');
+                return `const {${destructuringPattern}}=await import(window.${globalVar}||"${relativePath}");`;
+              });
+            }
+          }
+        }
+
+        // Step 3: Rewrite imports to UNMANAGED chunks in MANAGED chunks.
+        // Managed chunks are loaded via Blob URLs. Relative imports fail in Blob URLs.
+        // Absolute paths (e.g. "/assets/foo.js") work but depend on the app being at domain root.
+        // To support subdirectories (and typical "base: './'" configs), we usage dynamic imports
+        // with runtime URL resolution against `document.baseURI`.
+        for (const fileName in managedChunks) {
+          const chunk = managedChunks[fileName];
+          // Check all imports designated by Rollup
+          chunk.imports.forEach((importedFile: string) => {
+            // If the importedFile is NOT in chunkInfo, it is unmanaged.
+            if (!chunkInfo[importedFile]) {
+              const importedBasename = importedFile.split('/').pop()!;
+              const escapedName = importedBasename.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+
+              // We need to match the full import statement to rewrite it to a destructuring assignment
+              // Pattern: import { a as b, c } from "./foo.js";
+              const pattern = `import\\s*\\{([^}]+)\\}\\s*from\\s*['"]\\.\\/${escapedName}['"];?`;
+              const importRegex = new RegExp(pattern, 'g');
+
+              if (importRegex.test(chunk.code)) {
+                chunk.code = chunk.code.replace(importRegex, (_match: string, bindings: string) => {
+                  const destructuringPattern = bindings.split(',').map(b => {
+                    const parts = b.trim().split(/\s+as\s+/);
+                    return parts.length === 2 ? `${parts[0]}:${parts[1]}` : parts[0];
+                  }).join(',');
+                  // Rewrite to dynamic import using document.baseURI to resolve the path correctly relative to the page
+                  return `const {${destructuringPattern}}=await import(new URL("${importedFile}", document.baseURI).href);`;
+                });
+              }
+
+              // Also handle side-effect imports if any? (Likely not for vendor chunks, but good to be safe?)
+              // For now, focusing on named imports as that's what Rollup outputs for code splitting.
+            }
+          });
+        }
+
+        // Step 4: Calculate final hashes and build manifest
+        // Now that code is modified (rewritten), we calculate the hash of the ACTUAL content that will be on disk.
+        // This ensures that if the rewrite logic changes (e.g. absolute paths), the hash changes, busting the COS cache.
+        const manifest: Record<string, any> = {};
+        for (const fileName in chunkInfo) {
+          const { chunk, globalVar } = chunkInfo[fileName];
+          const finalHash = crypto.createHash('sha256').update(chunk.code).digest('hex');
+
+          manifest[fileName] = {
+            file: `/${fileName}`,
+            hash: finalHash,
+            globalVar: globalVar
+          };
+        }
+
+        manifest['index'] = {
+          file: `/${mainChunk.fileName}`
+        };
+
+        // Inject loader and inlined manifest into index.html
+        if (htmlAsset) {
+          try {
+            let loaderCode = fs.readFileSync(loaderPath, 'utf-8');
+            loaderCode = loaderCode.replace('__COS_MANIFEST__', JSON.stringify(manifest));
+
+            let htmlSource = htmlAsset.source as string;
+
+            // Remove modulepreload links to avoid double fetching keys we manage
+            htmlSource = htmlSource.replace(
+              /<link\s+[^>]*rel=["']modulepreload["'][^>]*>/gi,
+              '<!-- modulepreload disabled by COS Plugin -->'
+            );
+
+            // Inject into head
+            htmlAsset.source = htmlSource.replace(
+              '<head>',
+              () => `<head>\n<script id="cos-loader">${loaderCode}</script>`
+            );
+          } catch (e) {
+            console.error('COS Plugin: Failed to read loader.js', e);
+          }
+        }
+      }
+    }
+  };
+}

package/loader.js

@@ -0,0 +1,94 @@
+(async function () {
+  await new Promise(resolve => setTimeout(resolve, 100));
+
+  const isCOSAvailable = 'crossOriginStorage' in navigator;
+  console.log('COS Loader: isCOSAvailable =', isCOSAvailable);
+
+  // Manifest is injected by the Vite plugin
+  // @ts-ignore
+  const manifest = __COS_MANIFEST__;
+
+  const mainEntry = manifest && manifest['index'];
+  if (!mainEntry) {
+    console.warn('COS Loader: Missing main entry in manifest.');
+    return;
+  }
+
+  // Identify managed chunks (anything with a hash)
+  const chunksToLoad = Object.values(manifest).filter(item => item.hash);
+
+  async function getBlobFromCOS(hash) {
+    if (!isCOSAvailable) return null;
+    try {
+      const handles = await navigator.crossOriginStorage.requestFileHandles([
+        { algorithm: 'SHA-256', value: hash },
+      ]);
+      if (handles && handles.length > 0) {
+        return await handles[0].getFile();
+      }
+    } catch (err) {
+      if (err.name !== 'NotFoundError') console.error('COS Loader: Error checking COS', err);
+    }
+    return null;
+  }
+
+  async function storeBlobInCOS(blob, hash) {
+    if (!isCOSAvailable) return;
+    try {
+      const handles = await navigator.crossOriginStorage.requestFileHandles(
+        [{ algorithm: 'SHA-256', value: hash }],
+        { create: true }
+      );
+      if (handles && handles.length > 0) {
+        const writable = await handles[0].createWritable();
+        await writable.write(blob);
+        await writable.close();
+        console.log('COS Loader: Stored bundle in COS', hash);
+      }
+    } catch (err) {
+      console.error('COS Loader: Failed to store in COS', err);
+    }
+  }
+
+  // Load all managed chunks in parallel
+  // If COS is not available, we skip this and fall back to native network loading via the import() rewrites.
+  if (isCOSAvailable && chunksToLoad.length > 0) {
+    await Promise.all(chunksToLoad.map(async (chunk) => {
+      let url = null;
+
+      const cosBlob = await getBlobFromCOS(chunk.hash);
+      if (cosBlob) {
+        console.log(`COS Loader: Loaded ${chunk.file} from COS!`);
+        url = URL.createObjectURL(new Blob([cosBlob], { type: 'application/javascript' }));
+      } else {
+        console.log(`COS Loader: ${chunk.file} not in COS, fetching...`);
+        try {
+          const response = await fetch(chunk.file);
+          if (response.ok) {
+            const blob = await response.blob();
+            url = URL.createObjectURL(new Blob([blob], { type: 'application/javascript' }));
+            // Store in COS for next time
+            storeBlobInCOS(blob, chunk.hash);
+          } else {
+            console.error(`COS Loader: Fetch failed with status ${response.status}`);
+          }
+        } catch (e) {
+          console.error(`COS Loader: Network fetch failed for ${chunk.file}`, e);
+        }
+      }
+
+      // Set global variable if we have a URL
+      if (url && chunk.globalVar) {
+        window[chunk.globalVar] = url;
+      }
+    }));
+  }
+
+  // Start App
+  try {
+    console.log('COS Loader: Starting app...');
+    await import(mainEntry.file);
+  } catch (err) {
+    console.error('COS Loader: Failed to start app', err);
+  }
+})();

package/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "vite-plugin-cross-origin-storage",
+  "version": "1.0.0",
+  "description": "Vite plugin to load chunks from Cross-Origin Storage",
+  "type": "module",
+  "main": "index.ts",
+  "files": [
+    "index.ts",
+    "loader.js"
+  ],
+  "peerDependencies": {
+    "vite": "^4.0.0 || ^5.0.0 || ^6.0.0 || ^7.0.0"
+  },
+  "dependencies": {
+    "@rollup/pluginutils": "^5.3.0"
+  }
+}