How to add real-time synchronization to your productivity-tool

In this tutorial, we will guide you through adding real-time synchronization to a productivity tool using SuperViz Collaboration and SuperViz Real-time. Real-time synchronization is a crucial feature for collaborative applications, allowing multiple users to interact with shared content simultaneously and see each other's changes as they happen. With SuperViz, you can build interactive tools that update live, providing a seamless collaborative experience for users.

We'll demonstrate how to integrate real-time synchronization into a notes application, enabling users to collaborate on notes with real-time updates. This setup allows multiple participants to edit notes, move elements, and see changes instantly as they happen. Let's get started!

Step 1: Set Up Your React Application

To begin, you'll need to set up a new React project where we will integrate SuperViz for real-time synchronization.

1. Create a New React Project

First, create a new React application using Vite with TypeScript.

1
npm create vite@latest realtime-notes-app -- --template react-ts
2
cd realtime-notes-app

2. Install SuperViz Packages

Next, install the necessary SuperViz packages, which will enable us to add real-time synchronization features to our application.

1
npm install @superviz/room @superviz/collaboration @superviz/realtime uuid

• @superviz/room: Core package for creating and managing SuperViz rooms.
• @superviz/collaboration: Package containing components for collaboration features like mouse pointers and who-is-online.
• @superviz/realtime: SuperViz Real-Time library for integrating real-time synchronization into your application.
• uuid: A library for generating unique identifiers, useful for creating unique participant IDs.

3. Configure tailwind

In this tutorial, we'll use the Tailwind css framework. First, install the tailwind package.

1
npm install -D tailwindcss postcss autoprefixer
2
npx tailwindcss init -p

We then need to configure the template path. Open tailwind.config.js in the root of the project and insert the following code.

1
/** @type {import('tailwindcss').Config} */
2
export default {
3
content: [
4
"./index.html",
5
"./src/**/*.{js,ts,jsx,tsx}",
6
],
7
theme: {
8
extend: {},
9
},
10
plugins: [],
11
}

Then we need to add the tailwind directives to the global CSS file. (src/index.css)

1
@tailwind base;
2
@tailwind components;
3
@tailwind utilities;

4. Set Up Environment Variables

Create a .env file in your project root and add your SuperViz developer key. This key will be used to authenticate your application with SuperViz services.

1
VITE_SUPERVIZ_API_KEY=YOUR_SUPERVIZ_DEVELOPER_KEY

Step 2: Implement the Main Application

In this step, we'll implement the main application logic to initialize SuperViz and handle real-time synchronization in a notes application.

1. Implement the App Component

Open src/App.tsx and set up the main application component with necessary imports:

1
import { useCallback, useEffect, useRef, useState } from "react";
2
import { createRoom } from "@superviz/room";
3
import {
4
  MousePointers,
5
  WhoIsOnline,
6
} from "@superviz/collaboration";
7
import { Realtime, type Channel } from "@superviz/realtime/client";
8
import { v4 as generateId } from "uuid";
9
import { NoteNode } from "./components/note-node";
10
import { Note } from "./common/types";
11

12
// SuperViz developer token ::
13
const DEVELOPER_TOKEN = import.meta.env.VITE_SUPERVIZ_API_KEY;
14

15
const ROOM_ID = "video-huddle-application";
16
const PARTICIPANT_ID = generateId();

Explanation:

• Imports: Import necessary components from React, SuperViz packages, and UUID for managing state, initializing SuperViz, and generating unique identifiers.
• Constants: Define the developer token, room ID, and a unique participant ID.

2. Create the App Component

Set up the main App component and initialize state variables.

1
export default function App() {
2
  const [initialized, setInitialized] = useState(false);
3
  const [notes, setNotes] = useState<Note[]>([]);
4
  const channel = useRef<Channel | null>(null);

Explanation:

• initialized: A state variable to track whether the SuperViz environment has been set up.
• notes: A state variable to manage the list of notes in the application.
• channel: A ref to store the real-time communication channel.

3. Initialize SuperViz and Real-Time Components

Create an initialize function to set up the SuperViz environment and configure real-time synchronization.

1
const initialize = useCallback(async () => {
2
    if (initialized) return;
3

4
    try {
5
      const room = await createRoom({
6
        developerToken: DEVELOPER_TOKEN,
7
        roomId: ROOM_ID,
8
        participant: {
9
          id: PARTICIPANT_ID,
10
          name: "Participant",
11
        },
12
        group: {
13
          id: "GROUP_ID",
14
          name: "GROUP_NAME",
15
        },
16
      });
17

18

19
      const mousePointers = new MousePointers("mouse-container");
20
      const whoIsOnline = new WhoIsOnline();
21
      room.addComponent(mousePointers);
22
      room.addComponent(whoIsOnline);

Explanation:

• initialize: An asynchronous function that checks if already initialized to prevent duplicate setups.
• createRoom: Creates a SuperViz room with participant and group details.
• Components: Creates and adds mouse pointers and who-is-online components to the room.

4. Set Up Real-Time Synchronization

Within the initialize function, set up real-time synchronization for notes.

1
const realtime = new Realtime(DEVELOPER_TOKEN, {
2
        participant: {
3
          id: PARTICIPANT_ID,
4
        },
5
      });
6

7
      channel.current = await realtime.connect("realtime-sync");
8
      channel.current.subscribe<Note>("note-change", (event) => {
9
        const note = event.data;
10

11
        if (event.participantId === PARTICIPANT_ID || !note) return;
12

13
        setNotes((previous) => {
14
          return previous.map((n) => {
15
            if (n.id === note.id) {
16
              return note;
17
            }
18

19
            return n;
20
          });
21
        });
22
      });

Explanation:

• Realtime: Initializes the real-time component for synchronization with participant information.
• connect: Connects to a specific channel named "realtime-sync".
• subscribe: Listens for "note-change" events and updates the local state accordingly, ignoring changes from the current participant to avoid redundancy.

5. Initialize Notes

Set the initial state of notes with example content and handle errors.

1
setInitialized(true);
2
      setNotes([
3
        {
4
          id: "note-1",
5
          title: `Unicorn's Shopping List`,
6
          content: "Rainbow sprinkles, cloud fluff, and pixie dust",
7
          x: 20,
8
          y: 50,
9
        },
10
        {
11
          id: "note-2",
12
          title: `Zombie's To-Do List`,
13
          content: "Find brains, practice groaning, shuffle aimlessly",
14
          x: 20,
15
          y: 50,
16
        },
17
        {
18
          id: "note-3",
19
          title: `Alien's Earth Observations`,
20
          content:
21
            "Humans obsessed with cat videos and avocado toast. Fascinating!",
22
          x: 20,
23
          y: 50,
24
        },
25
      ]);
26
    } catch (error) {
27
      console.error("Error initializing SuperViz Room:", error);
28
    }
29
  }, [initialized, setNotes]);

Explanation:

• setInitialized: Marks the application as initialized to prevent reinitialization.
• setNotes: Sets the initial notes with predefined content and positioning.
• Error Handling: Catches and logs any errors that occur during initialization.

6. Handle Note Changes

Implement the handleNoteChange function to manage updates to notes.

1
const handleNoteChange = useCallback((note: Note) => {
2
    setNotes((prevNotes) => {
3
      return prevNotes.map((n) => {
4
        if (n.id === note.id) {
5
          return note;
6
        }
7

8
        return n;
9
      });
10
    });
11

12
    if (channel.current) {
13
      channel.current.publish("note-change", note);
14
    }
15
  }, []);

Explanation:

• handleNoteChange: Updates the local state of notes when a note is edited and publishes the change to other participants.
• channel.current.publish: Sends the updated note to all participants through the real-time channel.

7. Use Effect Hook for Initialization

Use the useEffect hook to trigger the initialize function on component mount.

1
useEffect(() => {
2
    initialize();
3
  });

Explanation:

• useEffect: Calls the initialize function when the component mounts, setting up the SuperViz environment and real-time synchronization.

8. Render the Application

Return the JSX structure for rendering the application, including notes and collaboration features.

1
return (
2
    <>
3
      <div className="w-full h-full bg-gray-200 flex items-center justify-center flex-col">
4
        <header className="w-full p-5 bg-purple-400 flex items-center justify-between">
5
          <h1 className="text-white text-2xl font-bold">Real-Time Sync</h1>
6
        </header>
7
        <main
8
          id="mouse-container"
9
          className="flex-1 p-20 flex w-full gap-2 items-center justify-center overflow-hidden bg-canvas-background"
10
        >
11
          {notes.map((note, index) => (
12
            <NoteNode key={index} note={note} onChange={handleNoteChange} />
13
          ))}
14
        </main>
15
      </div>
16
    </>
17
  );

Explanation:

• Header: Displays the title of the application.
• Main Container: Has the ID "mouse-container" which matches the element ID used for mouse pointers.
• Notes Rendering: Maps through the notes array to render each note using the NoteNode component.

Step 3: Create the NoteNode Component

The NoteNode component is responsible for displaying individual notes and handling edits.

1. Create the NoteNode Component

Create a new file named src/components/note-node.tsx and add the following implementation:

1
import React, { useState } from "react";
2
import { Note } from "../common/types";
3

4
interface NoteNodeProps {
5
  note: Note;
6
  onChange: (note: Note) => void;
7
}
8

9
export const NoteNode: React.FC<NoteNodeProps> = ({ note, onChange }) => {
10
  const [title, setTitle] = useState(note.title);
11
  const [content, setContent] = useState(note.content);
12

13
  const handleTitleChange = (event: React.ChangeEvent<HTMLInputElement>) => {
14
    const newTitle = event.target.value;
15
    setTitle(newTitle);
16
    onChange({ ...note, title: newTitle });
17
  };
18

19
  const handleContentChange = (event: React.ChangeEvent<HTMLTextAreaElement>) => {
20
    const newContent = event.target.value;
21
    setContent(newContent);
22
    onChange({ ...note, content: newContent });
23
  };
24

25
  return (
26
    <div className="note-node p-4 bg-white rounded shadow-lg" style={{ position: "absolute", left: note.x, top: note.y }}>
27
      <input
28
        type="text"
29
        value={title}
30
        onChange={handleTitleChange}
31
        className="font-bold mb-2 w-full border-none focus:outline-none"
32
      />
33
      <textarea
34
        value={content}
35
        onChange={handleContentChange}
36
        className="w-full border-none focus:outline-none"
37
        rows={5}
38
      />
39
    </div>
40
  );
41
}

Explanation:

• NoteNode Component: Displays each note with editable fields for title and content.
• handleTitleChange & handleContentChange: Updates the state and calls the onChange callback to propagate changes.

2. Define the Note Type

Create a new file named src/common/types.ts and define the Note type.

1
export interface Note {
2
  id: string;
3
  title: string;
4
  content: string;
5
  x: number;
6
  y: number;
7
}

Explanation:

• Note Type: Defines the structure of a note, including ID, title, content, and position.

Step 4: Understanding the Project Structure

Here's a quick overview of how the project structure supports real-time synchronization:

1. App.tsx
   • Creates a SuperViz room using the createRoom function.
   • Sets up collaboration components like mouse pointers and who-is-online.
   • Handles real-time synchronization using the Realtime client.
2. NoteNode.tsx
   • Displays individual notes with editable fields.
   • Handles local state updates and propagates changes to the parent component.
3. types.ts
   • Defines the data structure for notes used throughout the application.

Step 5: Running the Application

1. Start the React Application

To run your application, use the following command in your project directory:

1
npm run dev

This command will start the development server and open your application in the default web browser. You can interact with the notes and see updates in real-time as other participants join the session.

2. Test the Application

• Real-Time Notes: Open the application in multiple browser windows or tabs to simulate multiple participants and verify that changes made to notes are reflected in real-time for all users.
• Collaborative Interaction: Test the responsiveness of the application by editing notes and observing how changes appear for other participants.

Summary

In this tutorial, we built a collaborative notes application using SuperViz for real-time synchronization. We used the @superviz/room package to create a room, the @superviz/collaboration package for mouse pointers and who-is-online features, and the @superviz/realtime package for synchronizing note changes between participants. This setup enables multiple users to collaborate seamlessly on shared notes, seeing each other's edits in real-time.

Feel free to explore the full code and further examples in the GitHub repository for more details.