Shared Workbook Revisions

Shared-workbook change tracking records every edit made by each contributor. The library reads and writes the three revision parts losslessly, so a workbook's full revision history survives a round-trip.

Parts

Attaching a Revision Log

Set revisionLog at the top level of WorkbookOptions. The structure mirrors the three parts:

import { generateWorkbook } from "@office-open/xlsx";

await generateWorkbook({
  worksheets: [{ name: "Data", rows: [{ cells: [{ value: "Product" }] }] }],
  revisionLog: {
    headers: {
      guid: "{HDR}",
      revisionId: 1,
      version: 2,
      headers: [
        {
          guid: "{H1}",
          dateTime: "2026-06-19T10:00:00Z",
          userName: "Alice",
          rId: "rId1",
          maxSheetId: 1,
          sheetIds: [1],
        },
      ],
    },
    logs: [
      {
        revisions: [
          {
            type: "cellChange",
            data: {
              rId: 1,
              sheetId: 1,
              newCellXml: `<nc r="A1" t="inlineStr"><is><t>foo</t></is></nc>`,
            },
          },
          {
            type: "comment",
            data: {
              sheetId: 1,
              cell: "B2",
              guid: "{CMT}",
              action: "add",
              author: "Alice",
              newLength: 5,
            },
          },
        ],
      },
    ],
    users: { users: [{ guid: "{U}", name: "Alice", id: 1, dateTime: "2026-06-19T10:00:00Z" }] },
  },
});

logs[i] corresponds to headers.headers[i] via its rId.

SharedWorkbookOptions

Revision Headers

RevisionHeadersOptions holds collection metadata (guid, revisionId, version, trackRevisions, preserveHistory, …) plus a headers[] array. Each RevisionHeaderEntry records one revision: guid, dateTime, userName, rId, maxSheetId, and sheetIds[].

Revision Entries

Each log's revisions[] is a discriminated union on type. Twelve revision kinds are supported:

rowColumn · move · customView · sheetRename · insertSheet · cellChange · formatting · autoFormatting · definedName · comment · queryTableField · conflict

{ type: "cellChange",  data: { rId, sheetId, newCellXml, oldCellXml?, … } }
{ type: "comment",     data: { sheetId, cell, guid, author, action?, … } }
{ type: "insertSheet", data: { rId, sheetId, name, sheetPosition, … } }

Verbatim XML fields

Revision entries that carry cell or differential-formatting data (cellChange, formatting, …) store the nested CT_Cell (nc/oc) and CT_Dxf (ndxf/odxf/dxf) content as raw XML strings — newCellXml, oldCellXml, newDxfXml, oldDxfXml, dxfXml. Their full content model is large and round-trip only needs lossless preservation, so they pass through verbatim rather than being re-authored.

Round-Trip

parseWorkbook reads all three parts back into the same revisionLog structure, so parse → generate preserves the complete revision history.