HyperFormula (v3.5.0)

View as Markdown

# File import and export

Import and export XLSX files, and import CSV files, with HyperFormula.

# Overview

HyperFormula imports and exports .xlsx files through the ExcelJS (opens new window) library. Import with the buildFromFile factory method and export with the toFile method.

ExcelJS is an optional peer dependency, so it is not installed with HyperFormula. Add it only if you use these two methods:

npm install exceljs

In Node.js, everything else in HyperFormula works without it: the library is loaded on demand, so calling buildFromFile or toFile without ExcelJS installed fails at the point of the call. A bundler such as webpack or esbuild, however, resolves the library when it builds your application, so the build fails if ExcelJS is not installed, even if your code never calls these two methods. In the UMD full build, ExcelJS is kept out of the bundle and has to be provided as the global ExcelJS.

For any other format (for example CSV), HyperFormula's factory methods accept standard JavaScript arrays, so you can plug in any third-party parser.

TIP

Only cell values and formulas are imported and exported. Cell styling, number formats, merged cells, charts, images, data validation, and other Excel-specific features are not preserved — HyperFormula stores only values and formulas. A cell that holds a value is exported as its value, so a number entered as a string, such as '1', is exported as a number. Formulas are converted between the syntax of the file (English function names, , between arguments, . as the decimal separator) and the language and separators your configuration uses. On export, formulas that use newer or dynamic-array Excel functions are written without Excel's internal _xlfn. prefix, so they may not resolve when the exported file is opened in real Excel.

# Import XLSX files

Pass the file's bytes (an ArrayBuffer or Uint8Array) to the asynchronous buildFromFile factory method. Reading the file itself is left to your environment, so the same API works in both Node.js and the browser.

# In Node.js

const fs = require('fs');
const { HyperFormula } = require('hyperformula');

async function importXlsx(filePath) {
  const data = fs.readFileSync(filePath); // a Buffer (a Uint8Array)
  const hf = await HyperFormula.buildFromFile(data, { licenseKey: 'gpl-v3' });

  console.log('Formulas:', hf.getSheetSerialized(0));
  console.log('Values:  ', hf.getSheetValues(0));

  return hf;
}

# In the browser

import { HyperFormula } from 'hyperformula';

// `file` is a File obtained from an <input type="file"> element.
async function importXlsx(file) {
  const data = await file.arrayBuffer(); // an ArrayBuffer
  const hf = await HyperFormula.buildFromFile(data, { licenseKey: 'gpl-v3' });

  return hf;
}

If the bytes cannot be read as an .xlsx file, buildFromFile rejects with an UnsupportedFileError.

# Export XLSX files

The asynchronous toFile method returns the workbook's bytes as a Uint8Array. Writing those bytes is left to your environment.

# In Node.js

const fs = require('fs');

async function exportXlsx(hf, filePath) {
  const bytes = await hf.toFile();
  fs.writeFileSync(filePath, bytes);
}

# In the browser

async function downloadXlsx(hf, fileName) {
  const bytes = await hf.toFile();
  const blob = new Blob([bytes], {
    type: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
  });

  const url = URL.createObjectURL(blob);
  const link = document.createElement('a');
  link.href = url;
  link.download = fileName;
  link.click();
  URL.revokeObjectURL(url);
}

# Import CSV files

HyperFormula has no built-in CSV parser. Use a third-party CSV parser (opens new window) (e.g., PapaParse (opens new window) or csv-parse (opens new window)), then pass the resulting array to buildFromArray.

# Advanced: custom XLSX handling

If you need control over how the workbook is read or written (for example, to read cached values instead of formulas, or to handle Excel features outside HyperFormula's value-and-formula model), parse the file yourself with a third-party XLSX parser (opens new window) such as ExcelJS (opens new window) or xlsx (opens new window), convert the result to JavaScript arrays, and pass them to buildFromSheets. See a full example on GitHub (opens new window).

← Release notes →