bigsheet-to-json

Convert public Google Sheets into structured JSON.

bigsheet-to-json reads one or more worksheets from a Google Sheet URL and converts rows into arrays of objects using the first row as headers.

No browser automation. No Playwright. No authentication required for public sheets.

Features

• Convert Google Sheets → JSON
• Read specific worksheets
• Auto-read all worksheets
• Use first row as object keys
• Trim header names
• Convert headers to camelCase
• Remove empty columns
• Remove empty rows
• Parse numbers automatically
• Parse dates automatically
• Configurable error handling

Installation

npm install bigsheet-to-json

Basic Usage

const { parseSheet } =
    require(
        "bigsheet-to-json"
    );

(async () => {
    const data =
        await parseSheet({
            url:
                "https://docs.google.com/spreadsheets/d/XXXXX/edit",

            tabs: [
                "Sheet1",
            ],
        });

    console.log(data);
})();

Example Output

Spreadsheet:

| Student Name | Gender | Grade | |-------------|--------|-------| | Alexandra | Female | 4 | | Andrew | Male | 1 |

Output:

{
  "Sheet1": [
    {
      "Student Name": "Alexandra",
      "Gender": "Female",
      "Grade": 4
    },
    {
      "Student Name": "Andrew",
      "Gender": "Male",
      "Grade": 1
    }
  ]
}

API

parseSheet(config)

Returns:

Promise<Object>

Parameters

| Property | Type | Required | Description | |----------|------|----------|-------------| | url | string | Yes | Google Sheet URL | | tabs | string[] | No | Worksheets to read | | options | object | No | Parsing options |

Configuration Options

trimHeaders

Remove leading/trailing spaces from headers.

Default:

true

Example:

" Student Name "

↓

"Student Name"

camelCaseHeaders

Convert headers into camelCase.

Default:

false

Example:

Student Name

↓

studentName

dropEmptyColumns

Remove properties with empty values.

Default:

true

Example:

Before:

{
  "name": "John",
  "email": ""
}

After:

{
  "name": "John"
}

dropEmptyRows

Remove rows with no values.

Default:

true

parseNumbers

Convert numeric strings into numbers.

Default:

true

Example:

Before:

{
  "price": "100"
}

After:

{
  "price": 100
}

parseDates

Convert detected dates into JavaScript Date.

Default:

true

Example:

Before:

{
  "createdAt": "2026-05-22"
}

After:

{
  createdAt:
    Date(...)
}

onError

Behavior when worksheet parsing fails.

Options:

"skip"
"throw"

Default:

"skip"

Example:

onError: "throw"

Parse Specific Worksheets

const data =
    await parseSheet({
        url,
        tabs: [
            "Students",
            "Teachers",
        ],
    });

Output:

{
  "Students": [],
  "Teachers": []
}

Parse All Worksheets

Omit tabs.

const data =
    await parseSheet({
        url,
    });

All worksheets will be parsed.

Full Example

const {
    parseSheet,
} =
require(
    "bigsheet-to-json"
);

(async () => {

const data =
await parseSheet({

url:
"https://docs.google.com/spreadsheets/d/XXXXX/edit",

options: {

trimHeaders:
true,

camelCaseHeaders:
true,

dropEmptyColumns:
true,

dropEmptyRows:
true,

parseNumbers:
true,

parseDates:
true,

onError:
"skip",

},

});

console.log(
JSON.stringify(
data,
null,
2
)
);

})();

Example output:

{
  "students": [
    {
      "studentName": "Alexandra",
      "grade": 4
    }
  ]
}

Requirements

• Node.js 18+

Notes

This package supports:

• Public Google Sheets
• Sheets shared with Anyone with the link

Private sheets require custom authentication.

License

MIT