node-google-spreadsheet

google-spreadsheet is a TypeScript library that wraps the Google Sheets v4 API into an ergonomic, promise-based interface for Node.js. It exposes both a row-based API (modeled after the older Sheets v3 conventions) for quick reads and writes of tabular data, and a lower-level cell-based API for fine-grained access to values, formulas, and formatting.

Authentication is handled through google-auth-library, supporting service accounts, OAuth2, raw access tokens, and API keys through a single unified interface. Requests are made via ky, which provides automatic retries with exponential backoff for rate-limited or failed calls. The library also supports managing whole documents — creating, deleting, sharing, and exporting spreadsheets — via the Drive API.

What You Get

• Row-based API for quick tabular reads/writes with optional TypeScript row typing
• Cell-based API for direct access to values, formulas, formatting, and notes
• Unified authentication supporting service accounts, OAuth2, raw tokens, and API keys
• Worksheet management: add, remove, resize, duplicate, and reorder sheets
• Document management via the Drive API: create, delete, share, and set public access
• Built-in automatic retries with exponential backoff for rate-limited requests

Common Use Cases

• Building internal admin tools backed by a spreadsheet instead of a database
• Syncing form submissions or app data into a shared Google Sheet
• Exporting reports or datasets into a spreadsheet for non-technical stakeholders
• Automating bulk updates or formatting across large existing spreadsheets

Under The Hood

Architecture The library is organized as a layered class hierarchy: GoogleSpreadsheet (src/lib/GoogleSpreadsheet.ts) owns document-level state and two ky HTTP instances (Sheets API and Drive API), each wired with a beforeRequest hook that resolves auth headers on every call regardless of which auth mode was passed in. GoogleSpreadsheetWorksheet wraps a single sheet, holding a sparse 2D cell cache and row/column metadata, and reaches back up through this._spreadsheet for any API calls it needs to make. GoogleSpreadsheetRow and GoogleSpreadsheetCell are thin leaf models over that cached data. Data flow is load-then-mutate: load*() methods populate local caches, while mutation methods queue batched update requests that funnel through the worksheet’s _makeSingleUpdateRequest up to the spreadsheet’s batch-update endpoint. Because every downstream class depends on the parent’s auth and ky setup, changes to GoogleSpreadsheet’s request plumbing would ripple through the entire class tree.

Tech Stack Written in strict-mode TypeScript, published as dual ESM/CJS output via tsdown. HTTP calls go through ky rather than axios or raw fetch, chosen specifically for its built-in configurable retry/backoff support. Authentication delegates to google-auth-library as a peer dependency, supporting JWT service accounts, OAuth2 clients, ADC, and API keys. es-toolkit supplies small lodash-style utilities (re-exported internally as toolkit.ts) to keep the dependency footprint minimal. The project uses bun as its package manager and dev runtime, vitest for tests, and varlock for type-safe environment variable handling in the test suite.

Code Quality The test suite under src/test/ is extensive, with dedicated files for rows, cells, worksheet operations and features, auth, data operations, rate limiting, and document management. Tests exercise real Google API calls against live service-account credentials rather than relying purely on mocks, though nock is available as a devDependency for interception where needed. Linting is enforced via ESLint with the airbnb-base/airbnb-typescript configs plus a custom no-floating-promise plugin to catch unhandled promises, and a Husky pre-commit hook runs checks locally. GitHub Actions CI runs lint and the full test suite on every push and pull request. TypeScript strict mode plus a generic getRows<T>() API give consumers compile-time safety over user-defined row shapes.

API Design The standout ergonomic choice is exposing both a row-based API (mirroring the simpler, older Sheets v3 style) and a cell-based API (exposing the full power of the v4 API) under one consistent interface, letting callers pick the right abstraction level per task rather than committing to one paradigm. Authentication is unified behind a small getAuthMode()/getRequestAuthConfig() pair so callers don’t need to branch on which google-auth-library class they’re holding. Generic-typed row access (getRows<T>()) gives IDE autocomplete and type errors on bad column names without any schema-generation step. Retry-with-backoff is on by default and configurable, so most callers never have to hand-roll their own rate-limit handling.