JavaScript | Web

You can integrate the Ditto SDK with your web and Node.js projects developed using JavaScript and TypeScript languages. 
For a complete overview of the platforms, transports, and devices the Ditto SDK supports, see Compatibility Maps﻿.
If you're using Node.js and want instructions on how to create a task app, see the Prebuilt Task App﻿ and the Basic Task App﻿ tutorial.
To install the JavaScript SDK:
1
﻿Prerequisites﻿: Confirm that you meet the minimum requirements.
2
﻿Install Dependencies﻿: Add the ditto package to your environment.
3
﻿Integrate Ditto﻿: Import and initialize Ditto in your app.
4
﻿Run Ditto﻿: Authenticate with the Big Peer and start syncing offline.
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:
bash
npm install @dittolive/ditto
npm install @dittolive/ditto
﻿
Integrating Ditto and Starting Sync
Import and initialize Ditto, and then provide your access credentials for one-time authentication with the Big Peer:
From the top-most scope of your app, import Ditto.
Using async/await, initialize Ditto.
Provide your access credentials by replacing the placeholders in the snippet below with values obtained from the Ditto portal:
Replace the appID placeholder value with the app ID that identifies your app in Ditto.
Replace the token placeholder value with your playground token that the Big Peer uses to verify your digital identity before issuing your playground certificate. 
Make sure to instantiate the ditto object in the top-most scope of your app. Otherwise, it may be inadvertently garbage collected and no longer accessible throughout the lifecycle of your app. 
For instructions on how to obtain your access credentials, see Sync Credentials﻿. For an introduction to authentication in Ditto, see Security > Authentication﻿.
JS
import { init, Ditto } from "@dittolive/ditto";

let ditto;
async function main() {
  await init()
  ditto = new Ditto({
    type: "onlinePlayground",
    appID: "YOUR_APP_ID",
    token: "YOUR_PLAYGROUND_TOKEN"
  })

  //Enable mutating DQL statements and ensure you only sync with peers using version 4.0 or higher of the Ditto SDK:
  await ditto.disableSyncWithV3()
  
  //initialize the sync process:
  ditto.startSync()
}

main()
import { init, Ditto } from "@dittolive/ditto";

let ditto;
async function main() {
  await init()
  ditto = new Ditto({
    type: "onlinePlayground",
    appID: "YOUR_APP_ID",
    token: "YOUR_PLAYGROUND_TOKEN"
  })

  //Enable mutating DQL statements and ensure you only sync with peers using version 4.0 or higher of the Ditto SDK:
  await ditto.disableSyncWithV3()
  
  //initialize the sync process:
  ditto.startSync()
}

main()
﻿
Running Ditto
You can now run your basic snippet using Node and should not see any errors:
Bash
node index.js
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:
JS
import { init, Ditto } from '@dittolive/ditto'

let ditto

async function main () {
  await init()

  ditto = new Ditto({
    type: "onlinePlayground",
    appID: "YOUR_APP_ID",
    token: "YOUR_PLAYGROUND_TOKEN"
  })
  
  //Enable mutating DQL statements and ensure you only sync with peers using version 4.0 or higher of the Ditto SDK:
  await ditto.disableSyncWithV3()
  
 //Initialize the sync process:
  ditto.startSync()

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

main()
import { init, Ditto } from '@dittolive/ditto'

let ditto

async function main () {
  await init()

  ditto = new Ditto({
    type: "onlinePlayground",
    appID: "YOUR_APP_ID",
    token: "YOUR_PLAYGROUND_TOKEN"
  })
  
  //Enable mutating DQL statements and ensure you only sync with peers using version 4.0 or higher of the Ditto SDK:
  await ditto.disableSyncWithV3()
  
 //Initialize the sync process:
  ditto.startSync()

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

main()
﻿
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.
For a step-by-step demonstration of how to create a basic task app, see the Basic Task App﻿ tutorial.
JS
import { init, Ditto } from '@dittolive/ditto'

let ditto

async function main () {
  await init()

  ditto = new Ditto({
    type: "onlinePlayground",
    appID: "YOUR_APP_ID",
    token: "YOUR_PLAYGROUND_TOKEN"
  })
  
  //Enable mutating DQL statements and ensure you only sync with peers using version 4.0 or higher of the Ditto SDK:
  await ditto.disableSyncWithV3()
  
  //Initialize the sync process:
  ditto.startSync()

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

  // 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:
  ditto.store.execute(`
    INSERT INTO tasks
    DOCUMENTS (:newTask)`,
    { newTask })
}

main()
import { init, Ditto } from '@dittolive/ditto'

let ditto

async function main () {
  await init()

  ditto = new Ditto({
    type: "onlinePlayground",
    appID: "YOUR_APP_ID",
    token: "YOUR_PLAYGROUND_TOKEN"
  })
  
  //Enable mutating DQL statements and ensure you only sync with peers using version 4.0 or higher of the Ditto SDK:
  await ditto.disableSyncWithV3()
  
  //Initialize the sync process:
  ditto.startSync()

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

  // 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:
  ditto.store.execute(`
    INSERT INTO tasks
    DOCUMENTS (:newTask)`,
    { newTask })
}

main()
﻿
﻿
Updated 06 May 2024
Did this page help you?
Kotlin
Node.js