node-red-contrib-officedocs

Node-RED nodes to create and manipulate Office documents: Excel (.xlsx), Word (.docx) and PowerPoint (.pptx) — without Microsoft Office.

| Node | Library | Format | |------|---------|--------| | exceljs | ExcelJS | .xlsx | | docx | docx | .docx | | pptx | PptxGenJS | .pptx |

Installation

# from the Node-RED user directory (usually ~/.node-red)
npm install node-red-contrib-officedocs

Or via the Node-RED Manage Palette UI → search node-red-contrib-officedocs.

Requirements

• Node.js ≥ 16
• Node-RED ≥ 2.0

Concepts

Document travels in msg.payload

Nodes are designed to be chained: the output of one node is the input of the next.

[inject]
  → [exceljs: create]
  → [exceljs: addSheet]
  → [exceljs: addRows]
  → [exceljs: write]      ← msg.payload = Buffer / path / base64
  → [http response]

Two outputs — success and error

Every node has two output ports:

• Port 1 — success: msg.payload contains the updated document.
• Port 2 — error: msg.error = { message, operation, params, stack }.

Panel fields vs msg.params

Every parameter can be configured in two ways (evaluated in priority order):

1. msg.params.fieldName — passed at runtime, highest priority.
2. Panel field — fixed value, TypedInput (str / num / bool / msg / env / JSONata), configured in the node editor.

Style and position parameters that consist of multiple sub-fields (color, bold, size, x, y, w, h…) are decomposed into individual panel fields. You can still pass the full object at runtime via msg.params to bypass all individual fields at once:

// panel fields are ignored when the full object is passed at runtime
msg.params = {
  style:     { bold: true, color: "2E75B6", size: 32 },   // docx heading
  position:  { x: 0.5, y: 0.5, w: 9, h: 1.5 },           // pptx
  textStyle: { fontSize: 36, bold: true, color: "FFFFFF" } // pptx
};

Runtime operation override

msg.operation = "addRow";          // overrides the operation dropdown
msg.params = { sheet: "Sales", rowValues: ["Q1", 48500] };

Flow context (shared document between parallel branches)

msg.contextKey = "myReport";  // all branches share the same workbook

The document is stored/retrieved from flow context rather than msg.payload. Clean up after use:

flow.set("myReport", null);

Write formats

| format | msg.payload after write | |----------|--------------------------| | buffer | Node.js Buffer | | base64 | Base64 string | | file | Absolute path of the written file |

Unit reference

| Unit | Used in | Conversion | |------|---------|-----------| | DXA (twips) | docx page size, margins, column widths, spacing | 1 inch = 1440 DXA · 1 cm ≈ 567 DXA | | Half-points | docx font size | 24 = 12 pt · 28 = 14 pt · 32 = 16 pt | | Points (pt) | ExcelJS font size, pptx font size, pptx line width | — | | Inches | pptx positions (x, y, w, h) | — | | Pixels | docx image width/height (at 96 dpi) | — | | ARGB hex | ExcelJS colors | 8 digits, no # — first 2 = alpha (FF = opaque) | | RGB hex | docx and pptx colors | 6 digits, no # |

Common docx page sizes in DXA:

| Format | Width | Height | |--------|-------|--------| | US Letter (portrait) | 12240 | 15840 | | A4 (portrait) | 11906 | 16838 | | A4 (landscape) | 16838 | 11906 |

ExcelJS Node

Creates and manipulates Excel workbooks.

Operations

create

Creates a new empty workbook.

msg.params = {
  creator:        "Node-RED",
  lastModifiedBy: "Node-RED"
};

read

Loads an existing .xlsx from disk or Buffer.

msg.params = {
  source: "/path/to/file.xlsx"  // string path or Buffer
};

addSheet

Adds a new worksheet.

msg.params = {
  sheetName: "Sales 2024",   // required — error if already exists
  tabColor:  "FF0000",       // optional — ARGB hex, no #
  sheetState: "visible"      // "visible" | "hidden" | "veryHidden"
};

addRow

Appends a single row.

msg.params = {
  sheet:     "Sales 2024",
  rowValues: ["Q1", "Rossi", 48500]   // array or { colName: value } object
};

addRows

Appends multiple rows in one call (more efficient than repeated addRow).

msg.params = {
  sheet:    "Sales 2024",
  rowsData: [
    ["Q1", "Rossi",   48500],
    ["Q2", "Bianchi", 52000]
  ]
};

setCell

Sets the value and/or style of a single cell.

msg.params = {
  sheet:     "Sales 2024",
  cell:      "B3",       // A1 notation or { row: 3, col: 2 }
  cellValue: 48500,      // prefix "=" for formulas: "=SUM(B1:B2)"
  // individual panel style fields: styleFontBold, styleFontSize, styleFontColor,
  // styleFillColor, styleNumFmt, styleAlignment
  // OR pass the full object to override all of them at once:
  style: {
    font:      { bold: true, size: 12, color: { argb: "FF0000FF" } },
    fill:      { type: "pattern", pattern: "solid", fgColor: { argb: "FFFFFF00" } },
    alignment: { horizontal: "center" },
    numFmt:    "#,##0.00"
  }
};

Color format: ExcelJS uses ARGB (8 hex digits, no #). FF000000 = opaque black, FFFF0000 = opaque red, FFFFFF00 = opaque yellow.

styleRange

Applies a style to a cell range (same style fields as setCell).

msg.params = {
  sheet: "Sales 2024",
  range: "A1:D1",        // A1:B2 notation
  style: { font: { bold: true, size: 12 } }
};

addTable

Inserts a structured Excel table.

msg.params = {
  sheet:          "Sales 2024",
  tableName:      "SalesTable",   // unique within the workbook
  tableRef:       "A1",
  tableStyle:     "TableStyleMedium9",
  showRowStripes: true,
  columns: [
    { name: "Quarter", filterButton: true },
    { name: "Agent",   filterButton: true },
    { name: "Amount",  filterButton: true, totalsRowFunction: "sum" }
  ],
  tableRows: [
    ["Q1", "Rossi",   48500],
    ["Q2", "Bianchi", 52000]
  ]
};

conditionalFormat

Adds conditional formatting rules to a range.

msg.params = {
  sheet:   "Sales 2024",
  range:   "C2:C100",
  cfRules: [
    {
      type: "cellIs", operator: "greaterThan", formulae: [50000],
      style: { fill: { type: "pattern", pattern: "solid", fgColor: { argb: "FF00FF00" } } }
    }
  ]
};

Common rule types: cellIs, expression, colorScale, dataBar, iconSet, top10.

mergeCell

Merges a range of cells. Merged cells display only the top-left cell's value.

msg.params = {
  sheet: "Sales 2024",
  range: "A1:D1"   // A1 notation range
};

Merging a range that already contains data preserves only the top-left value; all other cell values in the range are discarded.

setColumnWidth

Sets width and optionally hides a column.

msg.params = {
  sheet:     "Sales 2024",
  colRef:    "B",    // column letter or 1-based number
  colWidth:  20,     // character-width units (ExcelJS default ≈ 8.38)
  colHidden: false
};

setRowHeight

Sets height and optionally hides a row.

msg.params = {
  sheet:     "Sales 2024",
  rowNumber: 1,     // 1-based row number
  rowHeight: 30,    // points
  rowHidden: false
};

freezePanes

Freezes rows and/or columns so they stay visible when scrolling.

msg.params = {
  sheet:     "Sales 2024",
  freezeRow: 1,   // number of rows to freeze from the top (0 = none)
  freezeCol: 0    // number of columns to freeze from the left (0 = none)
};
// Freeze first row only: freezeRow=1, freezeCol=0
// Freeze first column only: freezeRow=0, freezeCol=1
// Freeze both: freezeRow=1, freezeCol=1

readCell

Reads the value and metadata of a single cell. The workbook is preserved in msg._doc.

msg.params = {
  sheet: "Sales 2024",
  cell:  "B3"      // A1 notation
};
// msg.payload → { address, value, text, type, formula }
// msg._doc    → original Workbook (chain continues via msg._doc)

readRange

Reads a rectangular range into a 2-D array of { value, text, type, formula } objects.

msg.params = {
  sheet: "Sales 2024",
  range: "A1:D10"
};
// msg.payload → 2-D array [ [ { value, text, type, formula }, … ], … ]
// msg._doc    → original Workbook

After readCell / readRange, pass msg._doc back into msg.payload in a function node if you want to continue modifying the workbook.

protect

Protects a worksheet with an optional password.

msg.params = {
  protectTarget: "sheet",          // "sheet" | "workbook"*
  sheet:         "Sales 2024",
  password:      "secret",         // optional — leave empty for no password
  // individual panel protection fields: protectSelectLocked, protectSelectUnlocked,
  // protectFormatCells, protectFormatColumns, protectFormatRows,
  // protectInsertRows, protectDeleteRows, protectSort, protectAutoFilter
  // OR pass the full object:
  options: {
    selectLockedCells:   true,
    selectUnlockedCells: true,
    formatCells:         false
  }
};

* target: "workbook" logs a warning and falls back to protecting all sheets — ExcelJS has limited workbook-level protection support.

write

Serializes the workbook.

msg.params = {
  format:   "buffer",             // "file" | "buffer" | "base64"
  filePath: "/reports/file.xlsx"  // required only when format = "file"
};
// msg._doc     → original Workbook (available after write)
// msg.payload  → serialized output

Docx Node

Creates Word documents from scratch.

Note: The document is assembled as an in-memory tree throughout the chain. The actual .docx file is built only at write time. Editing existing .docx files is not supported by the underlying library.

Operations

create

msg.params = {
  title:       "Q1 Report",
  author:      "Node-RED",
  pageSize:    { width: 12240, height: 15840 },           // DXA — US Letter
  margins:     { top: 1440, right: 1440, bottom: 1440, left: 1440 },  // DXA
  defaultFont: { name: "Arial", size: 24 }                // size in half-points
};

addHeading

msg.params = {
  headingText:  "Quarterly Results",
  headingLevel: 1,          // 1–6
  // individual panel style fields: headingBold, headingColor, headingFontSize
  // OR pass the full object to override all:
  style: { color: "2E75B6", bold: true, size: 32 }
};

Color is a 6-digit RGB hex without #. Font size is in half-points.

addParagraph

// Simple text with style
msg.params = {
  paraText:      "Hello world.",
  paraAlignment: "left",  // "left" | "center" | "right" | "justified" | "both"
  // individual panel style fields: paraBold, paraItalic, paraUnderline,
  // paraColor, paraFontSize, paraFont
  // OR pass the full object:
  style: { bold: false, italic: false, color: "333333", size: 24 }
};

// Mixed inline styles via runs (takes precedence over text and style fields)
msg.params = {
  paraRuns: [
    { text: "Normal " },
    { text: "bold",   bold: true },
    { text: " and " },
    { text: "italic", italic: true, color: "CC0000" }
  ],
  paraAlignment: "justified",
  paraSpacing:   { before: 120, after: 120 }  // twips
};

Run object shape: { text, bold, italic, underline, color, size, font, hyperlink }.

To add a clickable hyperlink inside a paragraph, include a hyperlink URL on any run:

msg.params = {
  paraRuns: [
    { text: "See the " },
    { text: "full report", hyperlink: "https://example.com/report", color: "1657F4" },
    { text: " for details." }
  ]
};

addList

msg.params = {
  listType:  "bullet",   // "bullet" | "number"
  listItems: [
    "First item",
    "Second item",
    { text: "Nested item", level: 1 },   // level 0–4
    "Third item"
  ]
};

addTable

msg.params = {
  tableRows:      [
    ["Quarter", "Agent",   "Amount"],
    ["Q1",      "Rossi",   "€48,500"],
    ["Q2",      "Bianchi", "€52,000"]
  ],
  tableHeaderRow: true,
  columnWidths:   [2500, 4000, 2500],   // DXA per column
  tableBorders:   true,
  // individual header style fields: tableHeaderBold, tableHeaderFill, tableHeaderColor
  // OR pass the full object:
  headerStyle: { bold: true, fill: "2E75B6", color: "FFFFFF" }
};

addImage

Width and height are in pixels (rendered at 96 dpi).

msg.params = {
  imageSource:  "/path/to/chart.png",  // path | Buffer | base64 data URI
  imageWidth:   400,
  imageHeight:  250,
  imageAltText: "Sales chart"
};

Supported image formats: PNG, JPG, GIF, BMP, SVG.

addHeader

Registers a page header. Call once per header type before write.

msg.params = {
  headerText:      "Confidential — Q1 Report",
  headerType:      "default",   // "default" | "first" | "even"
  headerAlignment: "right"      // "left" | "center" | "right"
};

| headerType | When it appears | |-------------|----------------| | default | All pages (unless overridden by first / even) | | first | First page only | | even | Even-numbered pages (requires Even & Odd Headers in Word) |

addFooter

Registers a page footer. Supports static text and automatic page numbers.

// Static text footer
msg.params = {
  footerText:        "Generated by Node-RED",
  footerType:        "default",
  footerAlignment:   "center",
  footerShowPageNum: false
};

// Footer with automatic page numbers ("Generated by Node-RED   Page 1 of 5")
msg.params = {
  footerText:        "Generated by Node-RED   ",
  footerAlignment:   "center",
  footerShowPageNum: true
};

When footerShowPageNum is true, Word field codes for Page X of Y are appended after the static text.

pageBreak

Inserts a page break. No params needed.

write

msg.params = {
  format:   "file",
  filePath: "/reports/report.docx"
};

PptxGenJS Node

Creates PowerPoint presentations.

The current slide is tracked internally (last added slide). Content operations target the current slide unless slideIndex (0-based) is specified.

Operations

create

msg.params = {
  layout:  "LAYOUT_16x9",   // "LAYOUT_16x9" | "LAYOUT_4x3" | "LAYOUT_WIDE"
                             // or custom via: { width: 12, height: 6.75 } (inches)
  author:  "Node-RED",
  company: "Acme Corp",
  theme:   { headFontFace: "Calibri", bodyFontFace: "Calibri" }
};

| Layout | Dimensions | |--------|-----------| | LAYOUT_16x9 | 10″ × 5.625″ | | LAYOUT_4x3 | 10″ × 7.5″ | | LAYOUT_WIDE | 13.33″ × 7.5″ |

addSlide

msg.params = {
  masterName: null,      // optional — registered master slide name
  bgColor:    "003366"   // optional — 6-digit hex background color
};
// The new slide becomes the current slide

For image backgrounds pass msg.params.bgColor = { path: "/img/bg.png" } — an object is forwarded directly to PptxGenJS.

addText

Position and style can be set as individual panel fields or passed as full objects via msg.params:

// Individual fields approach (can be set in the panel)
msg.params = {
  text:        "Slide title",
  slideIndex:  null,         // null = current slide
  posX: 0.5,  posY: 0.5,   // inches
  posW: 9,    posH: 1.5,
  textFontSize: 36,
  textBold:     true,
  textColor:    "FFFFFF",    // 6-digit hex, no #
  textAlign:    "left",      // "left" | "center" | "right" | "justify"
  textFontFace: "Calibri",
  textValign:   "middle",    // "top" | "middle" | "bottom"
  textWrap:     true
};

// Full-object approach (overrides all individual fields)
msg.params = {
  text:      "Slide title",
  position:  { x: 0.5, y: 0.5, w: 9, h: 1.5 },
  textStyle: { fontSize: 36, bold: true, color: "FFFFFF", align: "left", fontFace: "Calibri" }
};

addShape

// Individual fields approach
msg.params = {
  shapeType:      "rect",   // rect | ellipse | triangle | roundRect | …
  posX: 1, posY: 1, posW: 4, posH: 2,
  shapeFillColor: "4472C4",
  shapeLineColor: "002060",
  shapeLineWidth: 1
};

// Full-object approach
msg.params = {
  shapeType:  "rect",
  position:   { x: 1, y: 1, w: 4, h: 2 },
  shapeStyle: { fill: { color: "4472C4" }, line: { color: "002060", width: 1 } }
};

addImage

msg.params = {
  imageSource: "/path/to/logo.png",   // path | HTTP(S) URL | Buffer | base64 data URI
  imageType:   "png",                 // required when source is a Buffer
  posX: 0.5, posY: 1.5, posW: 4, posH: 3,
  sizing:    { type: "contain" },
  hyperlink: { url: "https://example.com", tooltip: "Visit site" }
};

addChart

msg.params = {
  chartType: "bar",   // "bar" | "line" | "pie" | "area" | "scatter" | "bubble" | "donut"
  posX: 0.5, posY: 1.5, posW: 8, posH: 4.5,
  chartData: [
    {
      name:   "Sales 2024",
      labels: ["Q1", "Q2", "Q3", "Q4"],
      values: [48500, 52000, 61000, 58000]
    }
  ],
  chartOptions: {
    showLegend: true, legendPos: "b",
    showTitle:  true, title: "Sales 2024"
  }
};

Multiple series: add more objects to the chartData array.

addTable

msg.params = {
  tableRows: [
    [
      { text: "Quarter", options: { bold: true, fill: "003366", color: "FFFFFF" } },
      { text: "Amount",  options: { bold: true, fill: "003366", color: "FFFFFF" } }
    ],
    [{ text: "Q1" }, { text: "€48,500" }]
  ],
  posX: 0.5, posY: 2, posW: 8,
  tableOptions: { colW: [3, 3], fontSize: 14 }
};

addNotes

Adds plain-text speaker notes to a slide. Notes appear in PowerPoint Presenter View but are not rendered on the slide itself.

msg.params = {
  notes:      "Remind the audience about the Q3 dip — supply chain disruption.",
  slideIndex: null   // null = current slide; 0-based index to target a specific slide
};

defineMaster

Defines a named slide master (background color or image, fixed objects on every slide). Must be called before any addSlide that references the master by name.

msg.params = {
  masterTitle:   "CORP_MASTER",   // unique name — referenced in addSlide.masterName
  masterBkg:     "1F3864",        // 6-digit hex solid background
  // OR an image background via msg.params at runtime:
  // masterBkg: { path: "/assets/bg.png" }
  masterObjects: [
    {
      type: "text",
      text: "CONFIDENTIAL",
      options: { x: 0.1, y: 5.3, w: 2, h: 0.3, fontSize: 10, color: "AAAAAA" }
    }
  ]
};

After defining the master, reference it in addSlide:

msg.params = { masterName: "CORP_MASTER" };

setLayout

msg.params = { layout: "LAYOUT_4x3" };

write

msg.params = {
  format:   "base64",              // "file" | "buffer" | "base64"
  filePath: "/reports/deck.pptx"   // required only when format = "file"
};

msg contract

Input

| Property | Type | Required | Description | |----------|------|----------|-------------| | msg.payload | Workbook / doc object / null | Yes (except create) | Document to operate on. | | msg.operation | string | No | Runtime override of the panel operation. | | msg.params | object | Depends | Operation parameters — override individual panel fields. Full style/position objects bypass individual fields entirely. | | msg.contextKey | string | No | Flow-context key for shared documents across parallel branches. |

Output — port 1 (success)

| Property | Type | Description | |----------|------|-------------| | msg.payload | document / Buffer / string | Updated document, or serialized output after write. | | msg._doc | document | Original document before write — useful for post-save processing. |

Output — port 2 (error)

| Property | Type | Description | |----------|------|-------------| | msg.error | object | { message, operation, params, stack } | | msg.payload | any | Original payload preserved for debugging. |

Flow examples

Excel — HTTP endpoint returning a .xlsx

[http in: GET /report]
  → [exceljs: create]
  → [function: set params]
  → [exceljs: addSheet]
  → [exceljs: addRows]
  → [exceljs: write]         format: buffer
  → [function: set headers]  Content-Type: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
  → [http response]

Word — generate from JSON body

[http in: POST /generate-doc]
  → [docx: create]
  → [docx: addHeading]    headingText = msg.payload.title
  → [docx: addParagraph]  paraText = msg.payload.body
  → [docx: addTable]      msg.params.tableRows = msg.payload.tableData
  → [docx: write]         format: base64
  → [http response]

PowerPoint — live KPI presentation

[inject / http in]
  → [http request: fetch KPIs]
  → [pptx: create]     layout: LAYOUT_16x9
  → [pptx: addSlide]   bgColor: 003366
  → [pptx: addText]    title with data
  → [pptx: addSlide]
  → [pptx: addChart]   time series data
  → [pptx: write]      format: file, filePath: /reports/kpi.pptx
  → [email: send attachment]

Import ready-to-use example flows from the examples/ folder in this package.

Compatibility

| Component | Version | |-----------|---------| | Node.js | ≥ 16.x | | Node-RED | ≥ 2.x | | ExcelJS | ^4.4.0 | | docx | ^8.5.0 | | PptxGenJS | ^3.12.0 |

Generated file compatibility

| Node | Compatible with | |------|----------------| | exceljs | Excel 2010+, LibreOffice Calc 6+, Google Sheets | | docx | Word 2013+, LibreOffice Writer 6+, Google Docs | | pptx | PowerPoint 2016+, LibreOffice Impress 6+, Google Slides |

Known limitations

| Node | Limitation | |------|-----------| | docx | Reading / editing existing .docx files is not supported — the docx library is write-only. | | pptx | Reading existing .pptx files is not supported — PptxGenJS is write-only. | | exceljs | protect: workbook has limited support in ExcelJS; the node warns and falls back to protecting all sheets individually. | | exceljs | Auto-fit column widths is not natively supported by ExcelJS — column widths must be set explicitly. | | pptx | Animated slide transitions are not supported by PptxGenJS. |

Known issues

• pptx / addSlide background image: the bgColor panel field only accepts a hex color string. To use an image background, pass the full object at runtime: msg.params.bgColor = { path: "/img/bg.png" }.
• exceljs / setCell dates: pass Date objects via msg.params.cellValue — the panel's TypedInput field returns a string, which ExcelJS stores as text rather than a date.

Roadmap

The following features are candidates for future releases, roughly ordered by implementation effort.

Completed ✅

• ExcelJS: mergeCell — merge a range of cells
• ExcelJS: setColumnWidth / setRowHeight — column/row sizing and visibility
• ExcelJS: freezePanes — freeze rows and columns
• ExcelJS: readCell / readRange — extract cell values from a loaded workbook
• ExcelJS: setActiveSheet — set a default sheet, avoids repeating sheet on every node
• ExcelJS: getInfo — workbook metadata (sheet names, row counts, used ranges)
• PptxGenJS: addNotes — speaker notes per slide
• PptxGenJS: defineMaster — named slide master with background and objects
• PptxGenJS: getSlideCount — slide count without modifying the presentation
• Docx: addHeader / addFooter — page headers and footers with optional page numbers
• Docx: hyperlinks inside paragraph runs (ExternalHyperlink)
• All nodes: node.status() visual indicator and msg.info contextual metadata on every output

Low effort

• ExcelJS: deleteSheet / renameSheet — remove or rename a worksheet; useful when working from .xlsx templates
• ExcelJS: autoFilter — add dropdown filter buttons to a range
• ExcelJS: addImage — embed an image into a worksheet (logos, charts exported as PNG)
• PptxGenJS: deleteSlide / reorderSlide — remove or move slides; needed for template-based generation
• Docx: addSection — section break with independent properties (e.g. a landscape page inside a portrait document)

Medium effort

• All nodes: batch mode — accept an array of operations in msg.payload and execute them in sequence inside a single node, reducing flow complexity for straightforward pipelines:

  msg.payload = [
    { op: 'addSheet', sheetName: 'Sales' },
    { op: 'addRows',  rowsData: [...] },
    { op: 'write',    format: 'buffer' }
  ];

• ExcelJS: template mode — open an existing .xlsx as base and only fill in data, preserving branding (borders, logos, styles)
• Docx: addTOC — automatic table of contents built from heading levels

Higher effort / library limitations

• ExcelJS: chart support (complex API, many chart types)
• Docx: table of contents with page numbers (requires Word field codes)
• All nodes: automated test suite (Jest/Mocha) covering the full create → add → write chain — prerequisite for 1.0.0
• All nodes: GitHub Actions CI running tests on Node.js 18 / 20 / 22

License

MIT © Davide Travaglini