To install the JavaScript SDK:

​

Prerequisites

Following are the minimum requirements that must be met before attempting to install Ditto.

• Node.js active or maintenance long-term support (LTS) version
• Linux, macOS version 11+, or Windows version 10+

​

Installing Dependencies

Install the @dittolive/ditto package into your project:

npm install @dittolive/ditto

​

Integrating Ditto and Starting Sync

Import and initialize Ditto, and then provide your access credentials for one-time authentication with Ditto Server:

1. From the top-most scope of your app, import Ditto.

2. Using async/await, initialize Ditto. In web applications, this will download Ditto’s WebAssembly binary. See section Web Assets for details on using this in a production environment.

3. Provide your access credentials by replacing the placeholders in the snippet below with values obtained from the Ditto portal:

   1. Replace the appID placeholder value with the app ID that identifies your app in Ditto.

   2. Replace the token placeholder value with your playground token that Ditto Server uses to verify your digital identity before issuing your playground certificate.

await init();

const ditto = new Ditto({
  type: "onlinePlayground",
  appID: "REPLACE_ME_WITH_YOUR_APP_ID",
  token: "REPLACE_ME_WITH_YOUR_PLAYGROUND_TOKEN",
  customAuthURL: "REPLACE_ME_WITH_YOUR_AUTH_URL",
  enableDittoCloudSync: false, // This is required to be set to false to use the correct URLs
});

ditto.updateTransportConfig((config) => {
  config.connect.websocketURLs.push(
    'wss://REPLACE_ME_WITH_YOUR_WEBSOCKET_URL'
  );
});

// Disable DQL strict mode so that collection definitions are not required in DQL queries
await ditto.store.execute("ALTER SYSTEM SET DQL_STRICT_MODE = false");

ditto.startSync();

​

Running Ditto

You can now run your basic snippet using Node and should not see any errors:

node index.js

​

Add a Sync Subscription

Add a sync subscription to receive updates on documents that match its query from connected peers in the mesh.

Use registerSubscription() in the ditto.sync namespace to add a sync subscription:

// Add a sync subscription:
ditto.sync.registerSubscription(`
  SELECT *
  FROM tasks
  WHERE isDeleted = false`);

​

Listening to Changes

Now that your app is ready to receive updates to documents from other peers, you might want to react to those changes as soon as they happen. For this you can use the registerObserver() method on ditto.store. The passed in callback closure is invoked by Ditto everytime it registers new changes to documents matching the query.

// Add a store observer:
ditto.store.registerObserver(`
  SELECT *
  FROM tasks
  WHERE isDeleted = false`,
  (result) => {
    console.log(`Tasks have been updated: ${result.items}`)
  }
);

const newTask = {
  isCompleted: false,
  isDeleted: false,
  body: "Hello world!"
};

// Insert a new document:
await ditto.store.execute(`
  INSERT INTO tasks
  VALUES (:newTask)`,
  { newTask });

​

Web Assets

When Ditto is used on the web, it needs to download a WebAssembly binary containing Ditto’s core logic. This happens automatically when calling await init(). By default, the SDK will fetch the asset from Ditto’s CDN.

Alternatively, you can host the binary on another CDN or web server and configure Ditto to retrieve it from there. You will find the file in the NPM package at web/ditto.wasm. Make it available on a web server and provide its URL when calling init():

await init({
  webAssemblyModule: 'https://some-custom-cdn.com/assets/ditto.wasm'
})

Make sure to properly configure the server to return the correct MIME type (application/wasm) and CORS headers.

Please consider your application’s loading UI while downloading the assets as it may take a few seconds to download and initialize the WebAssembly binary.

It is strongly recommended to serve assets using a web server or CDN that supports compression. This will significantly reduce the download size of assets and thereby the loading time of your application.