ShareJS - Concurrent Document Editing

Common errors

• Error: Cannot find module 'share'

  cause The 'share' package has not been installed or is not resolvable in the current environment.
  fix Run `npm install share` in your project directory to install the package.

• Error: Cannot find module 'livedb'

  cause The 'livedb' package, a mandatory dependency for ShareJS, has not been installed.
  fix Run `npm install livedb` in your project directory. Depending on your chosen storage, you might also need `livedb-mongo` or similar.

• TypeError: require(...).server.createClient is not a function

  cause Attempting to call `createClient` directly on the `share` module or `share.server` without properly requiring the `share` module, or using incorrect import syntax.
  fix Ensure you are using `var share = require('share');` and then `share.server.createClient(...)`. Double-check the exact casing and property access.

• Data synchronization errors or corrupted documents with Socket.IO

  cause Socket.IO, by default, does not guarantee in-order message delivery, which is a strict requirement for ShareJS's operational transformation to function correctly.
  fix Migrate to a transport like `node-browserchannel` or ensure your WebSocket implementation explicitly enforces in-order message delivery. Avoid relying on default Socket.IO behavior for ShareJS.

Warnings

• breaking The ShareJS project, including its core repository (share/ShareJS), appears to be abandoned. The last significant commit was around 2017. Users should be aware that there will likely be no further bug fixes, security patches, or feature development. Consider alternative, actively maintained operational transformation libraries.
  Fix: Evaluate actively maintained alternatives like Yjs, Automerge, or other collaborative editing frameworks. If continuing with ShareJS, be prepared to fork and maintain the codebase yourself.
• gotcha ShareJS requires a communication transport that guarantees in-order message delivery. Using libraries like `socket.io` directly without specific configuration can lead to messages arriving out of order, causing data corruption or synchronization issues.
  Fix: Utilize transports known to guarantee message order, such as `node-browserchannel`, or carefully configure your chosen WebSocket library (e.g., `ws`) to ensure strict ordering. Do not rely on `socket.io`'s default behavior for ShareJS communication without thoroughly understanding its ordering guarantees.
• gotcha The server-side API method to create a ShareJS instance is named `createClient`, which can be confusing as it creates a 'server' object that acts as a client to the LiveDB backend. This naming choice is explicit in the documentation but often leads to initial confusion.
  Fix: Remember that `require('share').server.createClient()` is the correct way to instantiate the ShareJS server component. The 'client' in the name refers to its interaction with the underlying LiveDB database.
• gotcha Documentation for the REST API and middleware (`share.use`) is partially external or incomplete within the main ShareJS repository. Users may need to consult separate repositories (`share/rest`, `share/middleware`) for full details, which might also suffer from the overall lack of maintenance.
  Fix: Refer to the linked repositories on GitHub for the most current (though potentially outdated) documentation for `share.rest()` and `share.use()`. Be prepared to examine the source code for undocumented behaviors.

Install

• npm install share npm
• yarn add share yarn
• pnpm add share pnpm

Imports

• livedb
  wrong:

  import livedb from 'livedb';

  correct:

  var livedb = require('livedb');

  ShareJS and its dependencies are primarily CommonJS modules. ESM 'import' syntax is not supported in this version.
• share
  wrong:

  import share from 'share';

  correct:

  var share = require('share');

  The main ShareJS library is imported via CommonJS 'require'. The 'share' object itself provides access to the server and other utilities.
• createClient
  wrong:

  var shareServer = require('share').createClient({backend: backend});

  correct:

  var shareServer = require('share').server.createClient({backend: backend});

  The server instance factory method `createClient` is nested under the `server` property of the main `share` export.

Quickstart

This quickstart initializes a ShareJS server with an in-memory LiveDB backend and sets up a WebSocket server to handle client connections, demonstrating the basic server-side setup.

const livedb = require('livedb');
const share = require('share');
const http = require('http');
const express = require('express');
const WebSocket = require('ws');

// 1. Initialize LiveDB backend (in-memory for simple example)
const backend = livedb.client(livedb.memory());

// 2. Create ShareJS server instance
const shareServer = share.server.createClient({backend: backend});

// 3. Set up HTTP server for serving client-side code (optional, but common)
const app = express();
app.use(express.static(__dirname + '/public')); // Serve static files

const httpServer = http.createServer(app);
const wss = new WebSocket.Server({ server: httpServer });

// 4. Handle WebSocket connections for ShareJS clients
wss.on('connection', (ws) => {
  const stream = WebSocket.createWebSocketStream(ws);
  shareServer.listen(stream);
  console.log('New ShareJS client connected via WebSocket.');
});

const PORT = process.env.PORT || 8000;
httpServer.listen(PORT, () => {
  console.log(`ShareJS server listening on http://localhost:${PORT}`);
  console.log('You will need a client-side implementation to connect.');
});