@componentor/fs 3.0.18 → 3.0.20

package/README.md

@@ -82,6 +82,7 @@ const fs = new VFSFileSystem({
   strictPermissions: false, // Enforce Unix permissions (default: false)
   sabSize: 4194304,       // SharedArrayBuffer size in bytes (default: 4MB)
   debug: false,           // Enable debug logging (default: false)
+  swUrl: undefined,       // URL of the service worker script (default: auto-resolved)
   swScope: undefined,     // Custom service worker scope (default: auto-scoped per root)
   limits: {               // Upper bounds for VFS validation (prevents corrupt data from causing OOM)
     maxInodes: 4_000_000,   // Max inode count (default: 4M)
@@ -160,6 +161,30 @@ console.log(fs.mode); // 'hybrid'
 
 `setMode()` terminates internal workers, allocates fresh shared memory, and reinitializes the filesystem in the requested mode.
 
+### Service Worker Setup (Multi-Tab)
+
+Multi-tab coordination requires a service worker that acts as a MessagePort broker between tabs. The built service worker is shipped at `dist/workers/service.worker.js`. Unlike regular workers (which are resolved by the bundler), **service workers must be served as a real file at a public URL**.
+
+Most bundlers (Vite, webpack) handle `new URL('./workers/service.worker.js', import.meta.url)` automatically, but if the default resolution doesn't work in your setup, use the `swUrl` option:
+
+```typescript
+const fs = new VFSFileSystem({
+  swUrl: '/vfs-service-worker.js', // your public URL
+});
+```
+
+**Vite example** — copy the file to `public/`:
+
+```bash
+cp node_modules/@componentor/fs/dist/workers/service.worker.js public/vfs-service-worker.js
+```
+
+```typescript
+const fs = new VFSFileSystem({ swUrl: '/vfs-service-worker.js' });
+```
+
+If you only use a single tab, the service worker is not needed — the tab always runs as the leader.
+
 ## COOP/COEP Headers
 
 To enable the sync API, your page must be `crossOriginIsolated`. Add these headers:
@@ -577,6 +602,12 @@ Make sure `opfsSync` is enabled (it's `true` by default). Files are mirrored to
 
 ## Changelog
 
+### v3.0.19-v3.0.20 (2026)
+
+**Features:**
+- Add `swUrl` config option to specify a custom service worker URL for multi-tab support in bundled environments where the default auto-resolved URL doesn't work
+- Remove `type: 'module'` from service worker registration (built output is plain script, not ESM)
+
 ### v3.0.18 (2026)
 
 **Features:**

package/dist/index.d.mts

@@ -167,8 +167,12 @@ interface VFSConfig {
     strictPermissions?: boolean;
     sabSize?: number;
     debug?: boolean;
+    /** URL of the service worker script. Defaults to `'./workers/service.worker.js'`
+     *  relative to `import.meta.url`. Override when the library is bundled and the
+     *  default relative URL no longer resolves to the correct location. */
+    swUrl?: string;
     /** Scope for the internal service worker registration. Defaults to
-     *  `'./opfs-fs-sw/'` (relative to the SW script URL) so it won't collide
+     *  `'./${ns}/'` (relative to the SW script URL) so it won't collide
      *  with the host application's service worker. */
     swScope?: string;
     /** Upper bounds for VFS validation (prevents corrupt data from causing OOM/hangs). */

package/dist/index.js

@@ -1351,6 +1351,7 @@ var VFSFileSystem = class {
       strictPermissions: config.strictPermissions ?? false,
       sabSize: config.sabSize ?? DEFAULT_SAB_SIZE,
       debug: config.debug ?? false,
+      swUrl: config.swUrl,
       swScope: config.swScope,
       limits: config.limits
     };
@@ -1560,9 +1561,9 @@ var VFSFileSystem = class {
   /** Register the VFS service worker and return the active SW */
   async getServiceWorker() {
     if (!this.swReg) {
-      const swUrl = new URL("./workers/service.worker.js", import.meta.url);
+      const swUrl = this.config.swUrl ? new URL(this.config.swUrl, location.origin) : new URL("./workers/service.worker.js", import.meta.url);
       const scope = this.config.swScope ?? new URL(`./${this.ns}/`, swUrl).href;
-      this.swReg = await navigator.serviceWorker.register(swUrl.href, { type: "module", scope });
+      this.swReg = await navigator.serviceWorker.register(swUrl.href, { scope });
     }
     const reg = this.swReg;
     if (reg.active) return reg.active;