Quickstart - Get started with a multiplayer Handsontable spreadsheet using Liveblocks and Next.js

Liveblocks is a realtime collaboration infrastructure for building performant collaborative experiences. Follow the following steps to start adding multiplayer to a Handsontable spreadsheet in your Next.js /app directory application using the hooks from @liveblocks/react.

Quickstart

1. Install Liveblocks and Handsontable

   Every Liveblocks package should use the same version.

   Terminal

   npm install @liveblocks/client @liveblocks/react @handsontable/react-wrapper handsontable

2. Initialize the liveblocks.config.ts file

   We can use this file later to define types for our application.

   Terminal

   npx create-liveblocks-app@latest --init --framework react

3. Define your Liveblocks types

   Inside the liveblocks.config.ts file, define the Storage and Presence types for your application. Storage will hold the grid data, and presence will track which cell each user has selected.

   liveblocks.config.ts

   import type { LiveList } from "@liveblocks/client";
   export const GRID_ROWS = 10;export const GRID_COLS = 5;
   declare global {  interface Liveblocks {    Presence: {      selectedCell: { row: number; col: number } | null;    };    Storage: {      grid: LiveList<LiveList<string>>;    };  }}

4. Create a Liveblocks room

   Liveblocks uses the concept of rooms, separate virtual spaces where people collaborate, and to create a realtime experience, multiple users must be connected to the same room. When using Next.js' /app router, we recommend creating your room in a Room.tsx file in the same directory as your current route.

   Set up a Liveblocks client with LiveblocksProvider, join a room with RoomProvider, and use ClientSideSuspense to add a loading spinner to your app.

   Pass initialPresence and initialStorage to set up the default presence and an empty grid.

   app/Room.tsx

   "use client";
   import { LiveList } from "@liveblocks/client";import { ReactNode } from "react";import {  LiveblocksProvider,  RoomProvider,  ClientSideSuspense,} from "@liveblocks/react/suspense";import { GRID_COLS, GRID_ROWS } from "../liveblocks.config";
   export function Room({ children }: { children: ReactNode }) {  return (    <LiveblocksProvider publicApiKey={"pk_prod_xxxxxxxxxx…xxxxxxxxpk_prod_xxxxxxxxxxxxxxxxxxxxxxxx"}>      <RoomProvider        id="my-room"        initialPresence={{ selectedCell: null }}        initialStorage={{          grid: new LiveList(            Array.from(              { length: GRID_ROWS },              () => new LiveList(Array.from({ length: GRID_COLS }, () => ""))            )          ),        }}      >        <ClientSideSuspense fallback={<div>Loading…</div>}>          {children}        </ClientSideSuspense>      </RoomProvider>    </LiveblocksProvider>  );}

5. Add the Liveblocks room to your page

   After creating your room file, it's time to join it. Import your room into your page.tsx file, and place your collaborative app components inside it.

   app/page.tsx

   import { Room } from "./Room";import { Table } from "./Table";
   export default function Page() {  return (    <Room>      <Table />    </Room>  );}

6. Set up the collaborative Handsontable spreadsheet

   Now that Liveblocks is set up, integrate Handsontable in the Table.tsx file. useStorage reads the grid data from Liveblocks Storage, and useMutation writes cell changes back. We also use presence to highlight which cell each user has selected.

   app/Table.tsx

   "use client";
   import { shallow } from "@liveblocks/client";import { HotTable } from "@handsontable/react-wrapper";import { registerAllModules } from "handsontable/registry";import { textRenderer } from "handsontable/renderers";import type { CellChange, ChangeSource } from "handsontable/common";import {  useMutation,  useOthersListener,  useStorage,} from "@liveblocks/react/suspense";import { useCallback, useRef } from "react";import type { HotTableRef } from "@handsontable/react-wrapper";import { GRID_COLS, GRID_ROWS } from "../liveblocks.config";
   registerAllModules();
   export function Table() {  const hotRef = useRef<HotTableRef>(null);
     // Get the realtime grid contents from Liveblocks Storage  const data = useStorage(    (root) =>      root.grid.map((row) =>        Array.from({ length: GRID_COLS }, (_, c) => String(row[c] ?? ""))      ),    shallow  );
     // Update a cell's value  const updateCell = useMutation(    ({ storage }, rowIndex: number, colIndex: number, value: string) => {      const grid = storage.get("grid");      const row = grid.get(rowIndex);      if (row) {        row.set(colIndex, value);      }    },    []  );
     // Update the grid when a cell is changed  const afterChange = useCallback(    (changes: CellChange[] | null, source: ChangeSource) => {      if (!changes || source === "loadData") {        return;      }
         for (const [row, prop, , newVal] of changes) {        if (typeof prop !== "number") {          continue;        }
           updateCell(          row,          prop,          newVal === null || newVal === undefined ? "" : String(newVal)        );      }    },    [updateCell]  );
     // Sync selected cell to presence  const syncSelectedCellToPresence = useMutation(    ({ setMyPresence }, row: number, col: number) => {      setMyPresence({        selectedCell: { row: row < 0 ? 0 : row, col: col < 0 ? 0 : col },      });    },    []  );
     const clearSelectedCellPresence = useMutation(({ setMyPresence }) => {    setMyPresence({ selectedCell: null });  }, []);
     // Render presence inside cells  const renderDataCell = useMutation(    ({ others }, ...props: Parameters<typeof textRenderer>) => {      textRenderer(...props);      const [, td, row, col] = props;
         // Find users who have selected this cell      const selectedOthers = others.filter(        (o) =>          o.presence.selectedCell?.row === row &&          o.presence.selectedCell?.col === col      );
         if (!selectedOthers.length) {        td.style.boxShadow = "";        return;      }
         // Add inner borders for selected users      td.style.boxShadow = selectedOthers        .map((p, i) => `inset 0 0 0 ${2 + i * 2}px ${p.info.color}`)        .join(", ");    },    []  );
     // Re-render the table when others update their presence  useOthersListener(({ type }) => {    if (type === "update") {      hotRef.current?.hotInstance?.render();    }  });
     return (    <HotTable      ref={hotRef}      data={data}      hotRenderer={renderDataCell}      afterChange={afterChange}      afterSelection={syncSelectedCellToPresence}      afterDeselect={clearSelectedCellPresence}      colHeaders={true}      rowHeaders={true}      height={400}      width={600}      licenseKey="non-commercial-and-evaluation"      autoWrapRow={true}      autoWrapCol={true}    />  );}

7. Next: set up authentication

   By default, Liveblocks is configured to work without an authentication endpoint where everyone automatically has access to rooms. This approach is great for prototyping and marketing pages where setting up your own security isn't always required. If you want to limit access to a room for certain users, you'll need to set up an authentication endpoint to enable permissions.

   Set up authentication

What to read next

Congratulations! You now have set up the foundation to start building a multiplayer Handsontable spreadsheet for your Next.js application.

• @liveblocks/react API Reference
• Next.js and React guides
• How to use Liveblocks Storage with React

Examples using Handsontable