{"id":11416,"library":"node-excel-export","title":"Node.js Excel Export","description":"node-excel-export is a Node.js module designed for generating `.xlsx` files from JavaScript datasets. It takes an array of objects as input along with a JSON-based report specification, allowing for flexible configuration of column headers, data mapping, and cell styling. The current stable version is 1.4.4. While its release cadence appears to be slow, suggesting a mature and largely feature-complete library, it remains functional for its stated purpose. Key differentiators include its ability to apply rich cell styling, dynamically reformat data using renderer functions, and define complex header rows and cell merges directly from a JavaScript configuration. It abstracts away the complexities of the underlying `xlsx` (js-xlsx) library for common export scenarios, providing a simpler API for generating Excel reports on the server side.","status":"maintenance","version":"1.4.4","language":"javascript","source_language":"en","source_url":"https://github.com/andreyan-andreev/node-excel-export","tags":["javascript","excel"],"install":[{"cmd":"npm install node-excel-export","lang":"bash","label":"npm"},{"cmd":"yarn add node-excel-export","lang":"bash","label":"yarn"},{"cmd":"pnpm add node-excel-export","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core dependency for creating and manipulating Excel files.","package":"xlsx","optional":false},{"reason":"Utility library used internally for data manipulation.","package":"lodash","optional":false},{"reason":"Potentially used for client-side file saving in browser contexts, though not strictly required for Node.js server-side export.","package":"file-saver","optional":true}],"imports":[{"note":"This package is CommonJS-only. Direct ESM imports are not supported without transpilation or Node.js's createRequire utility.","wrong":"import excel from 'node-excel-export';","symbol":"excel","correct":"const excel = require('node-excel-export');"},{"note":"buildExport is a method on the default CommonJS export, not a named export. Ensure you import the entire module first.","wrong":"import { buildExport } from 'node-excel-export';","symbol":"buildExport","correct":"const reportBuffer = excel.buildExport([...]);"}],"quickstart":{"code":"const excel = require('node-excel-export');\nconst fs = require('fs');\n\n// You can define styles as json object\nconst styles = {\n  headerDark: {\n    fill: {\n      fgColor: {\n        rgb: 'FF000000'\n      }\n    },\n    font: {\n      color: {\n        rgb: 'FFFFFFFF'\n      },\n      sz: 14,\n      bold: true,\n      underline: true\n    }\n  },\n  cellPink: {\n    fill: {\n      fgColor: {\n        rgb: 'FFFFCCFF'\n      }\n    }\n  },\n  cellGreen: {\n    fill: {\n      fgColor: {\n        rgb: 'FF00FF00'\n      }\n    }\n  }\n};\n\n//Array of objects representing heading rows (very top)\nconst heading = [\n  [{value: 'a1', style: styles.headerDark}, {value: 'b1', style: styles.headerDark}, {value: 'c1', style: styles.headerDark}],\n  ['a2', 'b2', 'c2'] // <-- It can be only values\n];\n\n//Here you specify the export structure\nconst specification = {\n  customer_name: { \n    displayName: 'Customer', \n    headerStyle: styles.headerDark, \n    cellStyle: function(value, row) { \n      return (row.status_id == 1) ? styles.cellGreen : {fill: {fgColor: {rgb: 'FFFF0000'}}}; \n    },\n    width: 120 \n  },\n  status_id: {\n    displayName: 'Status',\n    headerStyle: styles.headerDark,\n    cellFormat: function(value, row) { \n      return (value == 1) ? 'Active' : 'Inactive';\n    },\n    width: '10' \n  },\n  note: {\n    displayName: 'Description',\n    headerStyle: styles.headerDark,\n    cellStyle: styles.cellPink, \n    width: 220 \n  }\n}\n\n// The data set should have the following shape (Array of Objects)\nconst dataset = [\n  {customer_name: 'IBM', status_id: 1, note: 'some note', misc: 'not shown'},\n  {customer_name: 'HP', status_id: 0, note: 'some note'},\n  {customer_name: 'MS', status_id: 0, note: 'some note', misc: 'not shown'}\n]\n\n// Define an array of merges.\nconst merges = [\n  { start: { row: 1, column: 1 }, end: { row: 1, column: 10 } },\n  { start: { row: 2, column: 1 }, end: { row: 2, column: 5 } },\n  { start: { row: 2, column: 6 }, end: { row: 2, column: 10 } }\n]\n\n// Create the excel report. This function will return a Buffer.\nconst report = excel.buildExport(\n  [\n    {\n      name: 'Report',\n      heading: heading,\n      merges: merges,\n      specification: specification,\n      data: dataset\n    }\n  ]\n);\n\n// Save the buffer to a file\nfs.writeFileSync('report.xlsx', report);\nconsole.log('report.xlsx created successfully.');","lang":"javascript","description":"This quickstart demonstrates how to define styles, create heading rows, specify column structures, and generate an Excel (.xlsx) file from a dataset, saving it to disk."},"warnings":[{"fix":"Use `const excel = require('node-excel-export');` for importing the module in CommonJS environments.","message":"This package is CommonJS-only. Attempting to use `import` syntax directly in an ESM module without proper configuration (like `createRequire` or `type: \"commonjs\"` in package.json for the entry file) will result in errors.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Thoroughly test `cellStyle` and `cellFormat` functions with various data inputs to ensure they always return expected values or style objects according to the `xlsx` library's specifications. Always include a fallback or default style.","message":"Dynamic styling or formatting functions (`cellStyle`, `cellFormat`) must return valid style objects or formatted strings. Errors within these functions can lead to malformed Excel files or runtime exceptions during report generation.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Verify that all keys defined in the `specification` object (e.g., `customer_name`, `status_id`) correspond precisely to the property names in your `dataset` array of objects.","message":"The `specification` object's keys must exactly match the keys in your `dataset` objects for data to be correctly mapped to columns. Mismatched keys will result in empty cells.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Ensure you are importing the module using `const excel = require('node-excel-export');` and then calling `excel.buildExport(...)`.","cause":"Attempting to use `buildExport` as a named import or calling it on a non-module object, often due to incorrect CommonJS import syntax in an ESM context.","error":"TypeError: excel.buildExport is not a function"},{"fix":"Review your `dataset` to confirm it's an `Array<Object>` and your `specification` to ensure all properties like `displayName`, `headerStyle`, and `width` are correctly defined as shown in the documentation.","cause":"The `dataset` is not an array of objects, or the `specification` object is malformed or missing required properties, leading to `node-excel-export` failing to process the input correctly.","error":"Error: Invalid data or specification provided. Check your dataset and specification objects."},{"fix":"Double-check the data types in your `dataset`, ensure custom style/format functions return valid output, and confirm `merges` array defines valid row/column ranges without overlaps that could cause structural issues.","cause":"Generated Excel file is corrupt, often due to invalid data types passed to `xlsx` library, errors in custom `cellStyle` or `cellFormat` functions, or incorrect merge ranges.","error":"The file cannot be opened because there are problems with the contents."}],"ecosystem":"npm"}