node package manager



Build Status Coverage Status Dependency Status devDependency Status js-semistandard-style

Easily use a spreadsheet as an input format for your app


For applications with complicated configuration data, it may make sense to keep the configuration data in a spreadsheet format to postpone the task of creating an administration UI. Admin users can then use any spreadsheet tool to edit the configuration data in a somewhat user-friendly manner.

This library supports reading in data from a spreadsheet. The data is represented as a hash of sheets containing a hash of rows containing a hash of columns.

Empty rows are ignored, as are comment rows which are marked with a single # character in the first cell.

The library assumes a database like structure of the sheets in a spreadsheet file. Each sheet must have one row at the top with column headers. Each sheet should have an "id" column to reference the rows.

The library reads cell values as strings, unless te column name is suffixed with a type. The following types are supported:

  • :date - the value will be parsed using "sugar-date" into a JavaScript timestamp
  • :num - the value will be parsed as a number
  • ::ref - the value will stored as a reference to a row in the specified sheet.

The library supports reading sheets from a JavaScript object literal instead of a file for use in unit testing code that depends on the sheet data structure.


API documentation generated by Mocha

Dump tool

node script/dump.js

Diff tool

When keeping your spreadsheet under version control it helps to be able to easily see a diff between different versions of a spreadsheet.

Included in this module is script/diff.js which can be used as an external diff tool from your IDE. This will convert the sheet to JSON and then invoke an external diff tool on the resulting .json files.

For example, in WebStorm, use this configuration for their external diff tool:

  • Executable:
  • Parameters: /node_modules/sheet-reader/script/diff.js %1 %2 "${quote}${quote} diff ${left} ${right}"

In the parameters string the following replacements are made:

  • ${quote} are replaced with a double quote: "
  • ${left} and ${right} are replaced with the absolute path to the resulting .json file of the left and right version of the spreadsheet