yjs-bundle

bundles several yjs packages in a single module in order to avoid "Yjs was already imported" problems

Background

When using Yjs in a browser (or another no-build environment, typical import statements such as

import * as Y                from 'yjs'
import { WebsocketProvider } from 'y-websocket'
import { YKeyValue }         from 'y-utility/y-keyvalue'

may lead to a completely unpredictable behaviour of Yjs.

A brief look into the browser console will reveal one or multiple error messages starting with Yjs was already imported. This breaks constructor checks and will lead to issues!

As written by dmonad: this message has to be taken seriously - Yjs will not work as expected!

But how does it then become possible to use Yjs within a browser without having to use a build environment (which will collect all required imports and build a large package including every import only once - together with other advantages)?

One possibility is to just bundle Yjs and all packages that depend on it into one module which may then be safely imported into a script - such an approach is by no means elegant but makes Yjs usable even within no-build environments.

This is what this repo wants to provide.

It currently bundles

• Yjs
• y-indexeddb
• y-websocket
• y-webrtc
• y-keyvalue and
• y-lwwmap

into a single monolith.

Usage

As a consequence, import statements like those shown above will either have to be rewritten as

import * as Y                from 'https://rozek.github.io/yjs-bundle/dist/yjs-bundle.esm.js'
import { WebsocketProvider } from 'https://rozek.github.io/yjs-bundle/dist/yjs-bundle.esm.js'
import { YKeyValue }         from 'https://rozek.github.io/yjs-bundle/dist/yjs-bundle.esm.js'
import { LWWMap }            from 'https://rozek.github.io/yjs-bundle/dist/yjs-bundle.esm.js'

or - and that's the recommended approach - you will have to provide an importmap with the following contents:

<script type="importmap">
{
  "imports": {
    "yjs":          "https://rozek.github.io/yjs-bundle/dist/yjs-bundle.esm.js",
    "y-indexeddb":  "https://rozek.github.io/yjs-bundle/dist/yjs-bundle.esm.js",
    "y-websocket":  "https://rozek.github.io/yjs-bundle/dist/yjs-bundle.esm.js",
    "y-webrtc":     "https://rozek.github.io/yjs-bundle/dist/yjs-bundle.esm.js",
    "y-utility/y-keyvalue":"https://rozek.github.io/yjs-bundle/dist/yjs-bundle.esm.js",
    "y-lwwmap":     "https://rozek.github.io/yjs-bundle/dist/yjs-bundle.esm.js"
  }
}
</script>

and use the same import statements as shown in the docs.

The potential disadvantage of importmaps, however, is that you - or your customers - will need a reasonably modern browser. Definitely supported browsers include:

• Chrome ≥ 89
• MS Edge ≥ 89
• Safari ≥ 16.4
• Firefox ≥ 108
• Opera ≥ 76
   
  
• Chrome for Android ≥ 111
• Safari on iOS ≥ 16.4

(see "Can I use" for additional details, especially if your browser is not listed above)

Build Instructions

You may easily build this package yourself.

Just install NPM according to the instructions for your platform and follow these steps:

1. either clone this repository using git or download a ZIP archive with its contents to your disk and unpack it there
2. open a shell and navigate to the root directory of this repository
3. run npm install in order to install the complete build environment
4. execute npm run build to create a new build

You may also look into the author's build-configuration-study for a general description of his build environment.

License

MIT License