Setting Up a Realtime Editor using Tiptap, NextJS and Planetscale.

In our previous article, we spoke about setting up realtime editor using TipTap and Hocuspocus which is stateless. This means we don’t save the contents to database or load an data from database, in most cases we’ve to be doing this in order to persist the written content. We use realtime editors for collaborating with our team on a changelog , when writing help articles, or even writing a product requirements document on featureOS.

In this article, I will walkthrough the steps to do the same. Luckily Tiptap with its HocusPocus plugin provides it out of the box and comes quite flexible too.

Provisioning the database

For this demo, I have created a MySQL database using Planetscale and connecting to it with Prisma ORM

Install Prisma and Setup

Run the following commands from the root of our project.

1
bun add -D prisma
2
bun add @prisma/client
3
bunx prisma init --datasource-provider mysql

Once you run these commands the Prisma will get install and creates a schema file for us under prisma/schema.prisma

1
generator client {
2
  provider = "prisma-client-js"
3
}
4

5
datasource db {
6
  provider = "mysql"
7
  url = env("DATABASE_URL")
8
}

Now in your .env file (create if its not present) paste your database connection url that you obtain from your database provider DATABASE_URL

1
DATABASE_URL=mysql://ppppqm2lfof1929wnpqek:pscale_pw_V44YmuQBYrPnlqCnpDmWnjjgj6FJicRwOBb8RG8Vq6O@ap-south.connect.psdb.cloud/realtime-editor?sslaccept=strict

Now, lets create our schema, we need a table called documents in which we store the document id and content. This can be different for each application, just for our demo we’re creating the most basic ones. Update the following in your prisma schema file

1
generator client {
2
  provider = "prisma-client-js"
3
}
4

5
datasource db {
6
  provider = "mysql"
7
  url = env("DATABASE_URL")
8
}
9
model Document {
10
  id Int @id @default(autoincrement())
11
  tiptap_content String @db.Text
12
}

After you update, we need to publish the migration to our database, we use prisma db push for it

1
npx prisma db push && npx prisma generate

Once the changes are migrated, our db is good to go, now we need to create a Prisma client to make the calls. Create a new file under prisma/prismaClient.ts with the following contents

1
const { PrismaClient } = require('@prisma/client')
2
const prisma = new PrismaClient()
3
module.exports = prisma

Now we’re ready to setup our web socket server to handle the storage and retrieval or document part.

Server Side Setup

We need to configure the following two functions in our hocuspocus web socket server.

1. onStoreDocument
2. onLoadDocument

These two functions primary does the storing and retrieval of data from our desired backend store.

Lets modify our code little, in order to keep things clear I will create a new file called documentHelpers.js in which I will write these to functions

1
const onStoreDocument = () => {}
2
const onLoadDocument = () => {}
3

4
module.exports = {
5
  onStoreDocument,
6
  onLoadDocument
7
}

And will import these two in our main file server/hocuspocus-server.js

1
const { Hocuspocus } = require('@hocuspocus/server')
2
const { onStoreDocument, onLoadDocument } = require('./documentHelpers')
3

4
const server = new Hocuspocus({
5
  port: 1234,
6
  onStoreDocument,
7
  onLoadDocument
8
})
9

10
server.listen()

With the basic structure ready, now lets add the functionality for these two functions.

onStoreDocument

The onStoreDocument function will be called every time the document is updated in the client side to store in the data store of our preference.

HocusPocus will give us the document content in binary format which we need to convert to base64 and store in our db, we use js-base64 library for it

1
yarn add js-base64

In order to make the understanding simpler, the list of things you need to do in onStoreDocument are

1. Get the document and documentName
2. Validate the documentName if required
3. Encode the document to Y js Update format
4. Converted the encoded binary data to base64
5. Store the base64 in your database

Here is the sample code for the same with Prisma and MySQL DB in documentHelpers.js

1
const { fromUint8Array } = require('js-base64')
2
const Y = require('yjs')
3
const prisma = require('../prisma/prismaClient')
4

5
const onStoreDocument = async incomingData => {
6
  const { documentName, document } = incomingData
7
  if (!documentName) return Promise.resolve()
8
  const documentId = parseInt(documentName, 10)
9
  const state = Y.encodeStateAsUpdate(document)
10
  const dbDocument = fromUint8Array(state)
11
  const documentFromDB = await prisma.document.findUnique({
12
    where: {
13
      id: documentId
14
    }
15
  })
16

17
  if (!documentFromDB) {
18
    return prisma.document
19
      .create({
20
        data: {
21
          id: documentId,
22
          tiptap_content: dbDocument
23
        }
24
      })
25
      .then(() => {
26
        console.log('Document created')
27
      })
28
  }
29
  return prisma.document
30
    .update({
31
      where: {
32
        id: documentId
33
      },
34
      data: {
35
        tiptap_content: dbDocument
36
      }
37
    })
38
    .then(() => {
39
      console.log('Document updated')
40
    })
41
}
42

43
const onLoadDocument = () => {}
44

45
module.exports = {
46
  onStoreDocument,
47
  onLoadDocument
48
}

With this you’ll be able to store the document in your database for every update from all the connected clients. But in order to reduce frequent calling of onStoreDocument, we can use debounce to differ it. To do that just update our server/hocuspocus-server.js with the following configuration

1
const server = new Hocuspocus({
2
  // ....
3
  debounce: 5000
4
})

We’ve solved one piece of the puzzle, which is storing the data to our store. But the bigger part is to load from the store when a user is trying to load the content in the client side.

onLoadDocument

The onLoadDocument function handles the extraction and sending the document format to our clients when a new editor is connected to a specific document.

Similar to storing part, I will first summarise the step to do before the code,

1. Get the document name from the incoming data
2. Find the base64 content in DB and extract it
3. Convert the base64 content back to unit8Array
4. Apply an Y js update with incoming document
5. Return the document

So lets code these steps in onLoadDocument, import toUint8Array function from js-base64 and add the below code to server/documentHelpers.js file

1
const onLoadDocument = async incomingData => {
2
  const { documentName, document } = incomingData
3
  if (!documentName) return Promise.resolve()
4
  const documentId = parseInt(documentName, 10)
5
  const documentFromDB = await prisma.document.findUnique({
6
    where: {
7
      id: documentId
8
    }
9
  })
10
  if (documentFromDB) {
11
    const dbDocument = toUint8Array(documentFromDB.tiptap_content || '')
12
    if (dbDocument) Y.applyUpdate(document, dbDocument)
13
    return document
14
  }
15
  return document
16
}

And we’re done with the server setup. We now need to do some changes to our client part to do the following

1. Create dynamic documents based on the URL
2. Load data from websocket server.

In order to create dyanmic path, I will move the /editor endpoint to /editor/[id] so that we can randomly create new realtime documents

1
mv src/pages/editor.tsx src/pages/editor/[id].tsx

In the new [id].tsx page get the id from the router query and send it to RichTextEditor as documentName

1
import dynamic from 'next/dynamic'
2
import { useRouter } from 'next/router'
3
import React from 'react'
4

5
const RichTextEditor = dynamic(
6
  () => import('../../components/RichTextEditor'),
7
  {
8
    ssr: false
9
  }
10
)
11

12
export default function EditorPage() {
13
  const router = useRouter()
14
  const { id } = router.query as { id: string }
15
  return <RichTextEditor documentName={id} />
16
}

And in the RichTextEditor lets receive the documentName from the props and initiate the provider with it.

1
import { HocuspocusProvider } from '@hocuspocus/provider'
2
import Collaboration from '@tiptap/extension-collaboration'
3
import CollaborationCursor from '@tiptap/extension-collaboration-cursor'
4
import { EditorContent, useEditor } from '@tiptap/react'
5
import StarterKit from '@tiptap/starter-kit'
6
import React from 'react'
7
import * as Y from 'yjs'
8

9
interface IPropTypes {
10
  documentName: string
11
}
12

13
export default function RichTextEditor({ documentName }: IPropTypes) {
14
  const ydoc = new Y.Doc()
15

16
  const provider = new HocuspocusProvider({
17
    url: 'ws://127.0.0.1:1234',
18
    name: documentName,
19
    document: ydoc,
20
    forceSyncInterval: 200
21
  })
22

23
  const editor = useEditor({
24
    extensions: [
25
      StarterKit,
26
      Collaboration.configure({
27
        document: ydoc
28
      }),
29

30
      CollaborationCursor.configure({
31
        provider,
32
        user: { name: 'John Doe', color: '#ffcc00' }
33
      })
34
    ],
35

36
    editorProps: {
37
      attributes: {
38
        class:
39
          'prose dark:prose-invert prose-sm sm:prose-base lg:prose-lg xl:prose-2xl m-5 focus:outline-none'
40
      }
41
    }
42
  })
43

44
  return <EditorContent editor={editor} />
45
}

That’s all! Now you have a realtime editor which can store and retrieve data from your own datastore.

In the next article, I’ll talk more about the permission setup for the documents with onAuthenticate function of hocuspocus server.