excel-templater

Fill Excel templates with data using n8n - supports UI forms and JSON arrays

Package Information

Downloads: 96 weekly / 110 monthly
Latest Version: 1.0.5
Author: Hueyan Chen

Available Nodes

Excel Templater icon
Excel Templater
Fill Excel templates with data using UI forms or JSON arrays

Documentation

n8n-nodes-excel-templater

npm version
License: MIT
Test Coverage

An enhanced n8n community node for filling Excel templates with data and generating new Excel files. Perfect for automating report generation, invoice creation, and data export workflows.

中文文檔 | Test Documentation

✨ Key Features

🎯 Dual Data Input Modes

  1. UI Form Mode (Recommended)

    • Graphical interface similar to the Set node
    • Add multiple data entries with ease
    • Intuitive and user-friendly
    • Support for single cells and table data

  2. JSON Array Mode (Legacy Compatible)

    • Maintains original JSON format
    • Ideal for programmatic operations
    • Backward compatible with older workflows

📊 Data Types Supported

Single Cell Input

  • Specify cell position (e.g., B2, C10)
  • Fill single values
  • Automatic type conversion: Numbers, booleans, dates, and null values are automatically detected and converted
    • "12345.67" → Number (12345.67)
    • "true"/"false" → Boolean
    • "2026-01-16" → Date object
    • "null"/"" → null
    • Other text → String

Table Data Input

  • Specify starting cell
  • Auto-expand JSON object arrays
  • Optional header row writing
  • Automatic handling of multi-row, multi-column data

🔧 Advanced Options

  • Multiple worksheet support: Write to specific sheets
  • File exists handling: Overwrite, rename, or throw error
  • Large dataset support: Tested with 1000+ rows
  • Special characters: Full Unicode and emoji support
  • Error handling: Continue on fail mode available

📦 Installation

Method 1: npm Installation (Recommended)

npm install n8n-nodes-excel-templater

Method 2: Community Nodes (n8n UI)

  1. Go to Settings > Community Nodes in n8n
  2. Click Install
  3. Enter n8n-nodes-excel-templater
  4. Click Install

Method 3: Manual Installation

cd ~/.n8n/nodes
git clone https://gitlab.com/hueyanchen-group/n8n-nodes-excel-templater.git
cd n8n-nodes-excel-templater
npm install
npm run build

🚀 Quick Start

Example 1: Fill Invoice Template

UI Form Mode

  1. Basic Configuration

    • Template Path: /data/invoice-template.xlsx
    • Output Path: /data/invoice-2024.xlsx
    • Data Input Mode: UI Form

  2. Add Single Cell Data

    • Click Add Entry
    • Entry Type: Single Cell
    • Cell: B2 (Invoice Number)
    • Value: INV-2024-001

  3. Add More Cells

    • Cell: B3, Value: John Doe (Customer Name)
    • Cell: B4, Value: 123 Main St (Address)
    • Cell: E2, Value: 2024-01-16 (Date)

  4. Add Table Data

    • Click Add Entry
    • Entry Type: Table Data
    • Start Cell: A8
    • Write Headers: true
    • Table Data:
      [
  {"Item": "Laptop", "Quantity": 2, "Price": 1200, "Total": 2400},
  {"Item": "Mouse", "Quantity": 5, "Price": 25, "Total": 125},
  {"Item": "Keyboard", "Quantity": 3, "Price": 75, "Total": 225}
]

Example 2: Employee Report

JSON Array Mode

[
  {"cell": "B1", "value": "Employee Report 2024"},
  {"cell": "B2", "value": "2024-01-16"},
  {"cell": "A5", "value": "Department: Sales"}
]

📖 Usage Guide

UI Form Mode - Single Cell

Perfect for filling specific cells in your template:

  • Cell: Excel cell reference (e.g., A1, B5, Z100)
  • Value: Any value (text, number, date, boolean)

Example Use Cases:

  • Invoice numbers
  • Customer names
  • Dates
  • Report titles

UI Form Mode - Table Data

Ideal for populating data tables:

  • Start Cell: Top-left cell of the table (e.g., A1, B5)
  • Table Data: JSON array of objects
  • Write Headers:
    • true: First row will contain object keys as headers
    • false: Data starts immediately at the start cell

How It Works:

Starting cell: B5, Write Headers: true

Input data:

[
  {"Product": "Notebook", "Qty": 100, "Price": 50},
  {"Product": "Pen", "Qty": 500, "Price": 10}
]

Result in Excel:

    B         C      D
5   Product   Qty    Price
6   Notebook  100    50
7   Pen       500    10

JSON Array Mode (Legacy)

For backward compatibility with older workflows:

[
  {"cell": "A1", "value": "Hello"},
  {"cell": "B1", "value": 123},
  {"cell": "C1", "value": true}
]

⚙️ Configuration Options

Template Path

  • Absolute path to your Excel template file
  • Example: /data/templates/invoice.xlsx
  • Supports .xlsx format

Output Path

  • Absolute path where the new file will be saved
  • Example: /data/output/invoice-2024.xlsx
  • Directory must exist

Data Input Mode

  • UI Form: Use graphical interface (recommended)
  • JSON Array: Use legacy JSON format

Options

If File Exists

  • Overwrite (default): Replace the existing file
  • Rename: Automatically append number (e.g., output-1.xlsx)
  • Error: Throw an error and stop execution

Worksheet Name

  • Manually type the worksheet name to write to
  • Leave empty to use the first worksheet
  • Example: Sheet1, Data, Summary
  • Note: Worksheet name is case-sensitive

🎨 Advanced Examples

Example 3: Mixed Data Types

// Single cells + Table in one workflow
{
  "entries": [
    {
      "entryType": "singleCell",
      "cell": "A1",
      "value": "Sales Report Q1 2024"
    },
    {
      "entryType": "singleCell", 
      "cell": "A2",
      "value": "Generated: 2024-01-16"
    },
    {
      "entryType": "tableData",
      "startCell": "A5",
      "writeHeaders": true,
      "tableData": [
        {"Month": "Jan", "Sales": 50000, "Target": 45000},
        {"Month": "Feb", "Sales": 55000, "Target": 50000},
        {"Month": "Mar", "Sales": 60000, "Target": 55000}
      ]
    }
  ]
}

Example 4: Multiple Worksheets

Process multiple sheets in the same workbook:

First execution: Write to Sheet1

  • Options > Worksheet Name: Sheet1
  • Add your data entries

Second execution: Write to Summary

  • Options > Worksheet Name: Summary
  • Add summary data

Example 5: Large Dataset

Handling 1000+ rows efficiently:

// Generate large dataset
{
  "entryType": "tableData",
  "startCell": "A1",
  "writeHeaders": true,
  "tableData": [
    // Array of 1000+ objects
    {"ID": 1, "Name": "Employee 1", "Department": "Sales"},
    {"ID": 2, "Name": "Employee 2", "Department": "IT"},
    // ... more rows
  ]
}

Performance: ~50-100ms for 1000 rows ⚡

📊 Supported Data Types and Auto-Conversion

Automatic Type Conversion (New in v1.0.2)

In UI Form Mode with Single Cell input, the node automatically detects and converts data types:

🔢 Numbers

When input looks like a number, it's automatically converted to numeric type:

  • "12345.67" → 12345.67 (number)
  • "100" → 100 (number)
  • "0" → 0 (number)
  • "-99.99" → -99.99 (number)

✅ Booleans

  • "true" → true (boolean)
  • "false" → false (boolean)

Note: Must be lowercase. Uppercase "TRUE" will be treated as a text string.

📅 Dates

Supports ISO 8601 format dates:

  • "2026-01-16" → Date object
  • "2026-01-16T10:30:00" → Date object
  • "2026-01-16T10:30:00.000Z" → Date object

⭕ Null Values

  • "null" → null
  • "undefined" → null
  • "" (empty string) → null

📝 Strings

Input that doesn't match any of the above rules remains as string:

  • "Hello World" → "Hello World" (string)
  • "TRUE" → "TRUE" (string)
  • "2026/01/16" → "2026/01/16" (string)

Conversion Priority

  1. Null detection (null, undefined, empty string)
  2. Boolean detection (true, false)
  3. Date detection (ISO 8601 format)
  4. Number detection (convertible to number)
  5. Keep as string (default)

All Supported Data Types

The node supports all ExcelJS data types:

Type Example Notes
String "Hello World" Any text, including Unicode and emoji
Number 123, 99.99, -50 Integers, decimals, negative numbers
Boolean true, false Displayed as TRUE/FALSE in Excel
Date "2024-01-16" ISO format recommended
Null/Undefined null, undefined Empty cells
Special Chars "@#$%^&*()" All special characters supported
Unicode/Emoji "😀🎉👍" Full Unicode support

🔍 Error Handling

Common Errors

Error Cause Solution
Template file not found Invalid template path Check file path exists
Worksheet not found Invalid worksheet name Verify worksheet name
Invalid JSON Malformed table data Validate JSON syntax
Invalid cell reference Wrong cell format Use format like A1, B2, Z100
Permission denied No write access Check file/folder permissions

Continue on Fail

Enable Continue on Fail in node settings to:

  • Continue processing remaining items on error
  • Return error information in output
  • Useful for batch processing

🧪 Testing

The node includes comprehensive test coverage:

  • 28 test cases covering all features
  • 100% code coverage (statements, functions, lines)
  • Tests for all data types and edge cases
  • Performance tests with 1000+ rows

Run tests:

npm test                    # Run all tests
npm run test:coverage      # Generate coverage report
npm run test:watch         # Watch mode

See Test Documentation for details.

🎯 Use Cases

Business Reports

  • Monthly sales reports
  • Financial statements
  • Inventory reports
  • KPI dashboards

Documents

  • Invoices and receipts
  • Purchase orders
  • Delivery notes
  • Certificates

Data Export

  • Database to Excel export
  • API data to Excel
  • CRM data export
  • Survey results

Form Filling

  • Government forms
  • Application forms
  • Registration forms
  • Template-based documents

🔒 Security & Privacy

  • All processing happens locally in your n8n instance
  • No data is sent to external services
  • Files remain on your server
  • Open source and auditable

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

  1. Fork the repository
  2. Create your feature branch (git checkout -b feature/AmazingFeature)
  3. Commit your changes (git commit -m 'Add some AmazingFeature')
  4. Push to the branch (git push origin feature/AmazingFeature)
  5. Open a Pull Request

Development

# Install dependencies
npm install

# Build
npm run build

# Watch mode
npm run dev

# Run tests
npm test

# Lint
npm run lint
npm run lintfix

📝 Changelog

v1.0.5

  • Fix: Date strings (ISO format or common date formats) are kept as strings.

v1.0.4

  • Repo migrated from GitHub to GitLab - Updated related repository URLs.

v1.0.3 (2026-03-01) 🔧

  • 🔧 Critical Fix: Node can now be added by drag-and-drop or double-click
  • 🛡️ Enhanced Error Handling: Template file validation, auto-create output directory, worksheet existence check
  • 🐛 Bug Fixes: Rename counter logic, table data column alignment, missing field handling
  • 📊 Testing: 35/35 tests passing with new test cases for edge scenarios
  • 🔄 Breaking Change: Worksheet Name changed from dropdown to manual text input

v1.0.2 (2026-01-16) 🎯

  • 🎯 Automatic Type Conversion for single cell input (numbers, booleans, dates, null)
  • 📚 Enhanced documentation with type conversion examples
  • ✅ Comprehensive unit tests for type conversion

v1.0.1 (2024-01-XX)

  • ✨ Initial release with dual input modes
  • ✨ UI Form mode and JSON Array mode
  • ✨ Multiple worksheet support
  • ✅ 100% test coverage
  • ✨ Single cell and table data support
  • ✨ Custom worksheet selection
  • ✨ Multiple file handling options (overwrite/rename/error)
  • ✨ Full test coverage (28 test cases, 100% coverage)
  • ✨ Support for all data types including Unicode/emoji
  • ✨ High performance (1000+ rows in <100ms)

📄 License

MIT License

🔗 Resources

🙏 Acknowledgments

💬 Support

Made with ❤️ for the n8n community

Discussion