Skip to content

installation.md

Latest commit

 

History

History
82 lines (58 loc) · 2.83 KB

installation.md

File metadata and controls

82 lines (58 loc) · 2.83 KB
Raw

Installation

Every way to install and load the library — npm with any bundler, and from a CDN with no build step at all.

← Back to the readme.

Installation

Two ways in. Both give you the identical library — the difference is only whether you have a build step.

With npm

For any bundler or framework — Vite, webpack, Next.js, Rollup, esbuild:

npm install @componentor/fs
import { VFSFileSystem } from '@componentor/fs';

No bundler configuration is needed. The worker bundles are embedded in the package, so there is nothing to resolve, copy or host — verified against vite dev and vite build with a config containing nothing but the isolation headers. TypeScript types are included.

The one exception is the multi-tab service worker: a service worker must be a real file at a URL, and the default lookup next to the library's own module fails under bundlers (see below). A single-tab app needs nothing; for multiple tabs, pass swUrl — under Vite that is one import:

import { VFSFileSystem } from '@componentor/fs';
import swUrl from '@componentor/fs/sw?url&no-inline';

const fs = new VFSFileSystem({ swUrl });

Details and the alternatives are in Multiple tabs.

The same package is also published as sync-opfs if you prefer that name: npm install sync-opfs.

From a CDN, with no build step

Nothing to install. Works in a plain .html file:

<script type="module">
  import { VFSFileSystem } from 'https://esm.sh/@componentor/fs';

  const fs = new VFSFileSystem({ root: '/my-app' });
  await fs.init();

  await fs.promises.writeFile('/hello.txt', 'Hello from a CDN');
  console.log(await fs.promises.readFile('/hello.txt', 'utf8'));
</script>

This works because the workers are embedded and started as same-origin blobs. Loading a browser filesystem from a CDN used to be impossible — a cross-origin new Worker() is a SecurityError — which is why versions before 4.0 could not be tried this way. Any CDN that serves ESM with CORS works; esm.sh, jsDelivr and unpkg all do.

If you would rather write bare specifiers without a bundler, use an import map:

<script type="importmap">
  { "imports": { "@componentor/fs": "https://esm.sh/@componentor/fs" } }
</script>
<script type="module">
  import { VFSFileSystem } from '@componentor/fs';
</script>

Remember the two headers. From a CDN you are usually on a static host, which means no crossOriginIsolated and therefore no sync API — the async API above works regardless. See COOP/COEP Headers, including a service-worker workaround that gets the sync API working on GitHub Pages.