Registry / gcp / google-spreadsheet

google-spreadsheet

library0.0.6jsnpmunverified

The `google-spreadsheet` package provides a robust and easy-to-use JavaScript/TypeScript interface for interacting with the Google Sheets API. It simplifies common tasks like reading, writing, and manipulating data within spreadsheets, as well as managing sheets and documents themselves. The current stable version is `5.2.0`, and the project maintains an active development cycle with frequent minor and patch updates for new features, bug fixes, and dependency synchronization. Key differentiators include comprehensive support for multiple authentication methods via `google-auth-library` (service account, OAuth 2.0, API key, ADC), both cell-based and row-based APIs for flexible data interaction, extensive methods for managing worksheets and documents (e.g., adding, removing, resizing, updating properties, setting permissions), and built-in automatic retries with exponential backoff for API requests, enhancing reliability against transient network issues and rate limits. It aims to be the most popular wrapper, abstracting away the complexities of the underlying Google Sheets API.

gcp database

npm install google-spreadsheet

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · GOOGLE-SPREADSHEET

google-spreadsheet

gcpjavascriptv0.0.6

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

GoogleSpreadsheet

✓ import { GoogleSpreadsheet } from 'google-spreadsheet';

✗ const GoogleSpreadsheet = require('google-spreadsheet');

Since v5.0.0, the library is primarily designed for ESM `import` statements and ships with TypeScript types. While CommonJS `require` might function in some setups, it's not the recommended or idiomatic approach.

JWT

✓ import { JWT } from 'google-auth-library';

✗ import { JWT } from 'google-spreadsheet';

Authentication classes like `JWT` are not directly exported by `google-spreadsheet`; they must be imported from the `google-auth-library` peer dependency.

GoogleSpreadsheetWorksheet (type)

✓ import type { GoogleSpreadsheetWorksheet } from 'google-spreadsheet';

For type-only imports in TypeScript, use `import type` to ensure they are correctly removed during compilation, avoiding potential runtime issues or unnecessary bundle size.

Demonstrates initializing the GoogleSpreadsheet client with service account credentials, loading document properties, and performing basic operations like reading/updating document/sheet titles and managing sheets.

import { GoogleSpreadsheet } from 'google-spreadsheet'; import { JWT } from 'google-auth-library'; // Initialize auth - use environment variables for security // process.env.GOOGLE_PRIVATE_KEY should have '\n' replaced with '\\n' if set as env var const serviceAccountAuth = new JWT({ email: process.env.GOOGLE_SERVICE_ACCOUNT_EMAIL ?? '', key: process.env.GOOGLE_PRIVATE_KEY?.replace(/\\n/g, '\n') ?? '', // Handle escaped newlines scopes: ['https://www.googleapis.com/auth/spreadsheets'], }); async function main() { const doc = new GoogleSpreadsheet(process.env.GOOGLE_SHEET_ID ?? '', serviceAccountAuth); await doc.loadInfo(); // loads document properties and worksheets console.log('Document title:', doc.title); await doc.updateProperties({ title: 'Renamed Doc via API' }); console.log('Updated document title to:', doc.title); const sheet = doc.sheetsByIndex[0]; // Access the first sheet console.log('First sheet title:', sheet.title); console.log('First sheet row count:', sheet.rowCount); // Adding and removing a new sheet const newSheet = await doc.addSheet({ title: 'Another Sheet ' + Date.now() }); console.log('Added new sheet:', newSheet.title); await newSheet.delete(); console.log('Deleted the new sheet.'); } // Run the main function (or wrap in an IIFE if top-level await is not supported) main().catch(console.error);

Debug

Known issues

breakingVersion 5.0.0 introduced significant modernization and dependency updates, particularly affecting `google-auth-library`. This may require adjustments if you were using older versions of `google-auth-library` (e.g., v8 or lower) or relied on internal behaviors prior to v5.

fix

Ensure your `google-auth-library` peer dependency is `>=8.8.0`. Review your authentication setup, as older patterns might be deprecated or incompatible. Refer to the official authentication guide.

affects: >=5.0.0

deprecatedDirect authentication methods like `doc.useServiceAccountAuth()` have been deprecated and removed. Users should now instantiate authentication clients (e.g., `JWT`, `GoogleAuth`) from `google-auth-library` and pass them directly to the `GoogleSpreadsheet` constructor.

fix

Replace calls to `doc.useServiceAccountAuth()` with creating an authenticated client from `google-auth-library` and passing it to `new GoogleSpreadsheet(id, authClient)`.

affects: >=4.1.1

gotchaThe example code often utilizes top-level `await`. This feature requires Node.js versions that support it (Node.js 14.8+ with ES modules, or Node.js 16+ without explicit module configuration). In older environments, top-level `await` will throw a syntax error.

fix

If your environment doesn't support top-level `await`, wrap your async code in an immediately invoked async function expression (IIFE): `(async () => { /* your code */ })();`.

affects: >=1.0.0

breakingThe peer dependency for `google-auth-library` was explicitly updated to `>=8.8.0`. Using older versions of `google-auth-library` with `google-spreadsheet` v5.x may lead to runtime errors or type conflicts.

fix

Upgrade your `google-auth-library` package to version `^8.8.0` or higher to ensure compatibility. For example: `npm install google-auth-library@latest`.

affects: >=5.0.0

gotchaWhen providing the `GOOGLE_PRIVATE_KEY` via an environment variable, newline characters (`\n`) within the key must be correctly escaped as `\\n` when setting the variable, and then unescaped when reading it back in JavaScript. Failure to do so will result in an invalid private key format.

fix

If setting `GOOGLE_PRIVATE_KEY` as an environment variable, ensure newlines are `\\n`. In your JavaScript code, you might need `process.env.GOOGLE_PRIVATE_KEY?.replace(/\\n/g, '\n')` to correctly parse it.

affects: >=1.0.0

gotchaPrior to v5.2.0, retrieving an empty cell might have yielded `undefined`. Since v5.2.0, empty cells are guaranteed to return an empty string (`''`), which could subtly affect existing logic that explicitly checks for `undefined`.

fix

Update your code to anticipate `''` for empty cell values when on or above v5.2.0, or explicitly handle both `undefined` and `''` if supporting a range of versions.

affects: <5.2.0

Errors

Common errors & fixes

TypeError: GoogleSpreadsheet is not a constructor

Attempting to use CommonJS `require()` syntax (`const { GoogleSpreadsheet } = require('google-spreadsheet');`) in an environment that expects ES modules, or with an incompatible module configuration.

fix

Ensure you are using ESM `import` syntax: `import { GoogleSpreadsheet } from 'google-spreadsheet';`. If using CommonJS, verify your build system or Node.js version supports this package's module format correctly.

Error: Missing credentials for 'JWT' (or similar 'credential.private_key should be a string' error)

The `GOOGLE_PRIVATE_KEY` environment variable or provided string is not formatted correctly, often due to incorrect handling of newline characters or a malformed key.

fix

Ensure the `key` property in your `JWT` constructor correctly represents the private key. If using `process.env`, replace escaped newlines: `key: process.env.GOOGLE_PRIVATE_KEY?.replace(/\\n/g, '\n') ?? ''`. Always double-check the private key format from your service account JSON.

Google API error: The caller does not have permission

The service account or API key used lacks the necessary permissions to access the specific Google Sheet or the Google Sheets API itself.

fix

Verify that the service account email has 'Editor' or 'Viewer' access to the target Google Sheet. Also, ensure the Google Sheets API is enabled for your project in the Google Cloud Console.

(node:...) UnhandledPromiseRejectionWarning: TypeError: Cannot read properties of undefined (reading 'loadInfo')

This typically occurs when `await` is used at the top level of a script without being inside an `async` function, and the Node.js version in use does not support top-level `await`.

fix

Wrap your top-level `await` calls within an immediately invoked async function expression (IIFE): `(async function() { /* your code here */ })();` or ensure your Node.js version supports top-level await.

Upgrade

Version history

0.0.6latest on npm

Audit

Dependencies

google-auth-libraryrequiredRequired for all authentication mechanisms used to access Google Sheets.

Agent activity

25 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/theoephraim/node-google-spreadsheet ↗

packagehttps://www.npmjs.com/package/google-spreadsheet ↗

homepagehttps://theoephraim.github.io/node-google-spreadsheet ↗