{"id":16042,"library":"google-spreadsheet","title":"Google Sheets API Client","description":"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.","status":"active","version":"5.2.0","language":"javascript","source_language":"en","source_url":"git://github.com/theoephraim/node-google-spreadsheet","tags":["javascript","google spreadsheets","google sheets","google","spreadsheet","spreadsheets","sheets","gdata","api","typescript"],"install":[{"cmd":"npm install google-spreadsheet","lang":"bash","label":"npm"},{"cmd":"yarn add google-spreadsheet","lang":"bash","label":"yarn"},{"cmd":"pnpm add google-spreadsheet","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required for all authentication mechanisms used to access Google Sheets.","package":"google-auth-library","optional":false}],"imports":[{"note":"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.","wrong":"const GoogleSpreadsheet = require('google-spreadsheet');","symbol":"GoogleSpreadsheet","correct":"import { GoogleSpreadsheet } from 'google-spreadsheet';"},{"note":"Authentication classes like `JWT` are not directly exported by `google-spreadsheet`; they must be imported from the `google-auth-library` peer dependency.","wrong":"import { JWT } from 'google-spreadsheet';","symbol":"JWT","correct":"import { JWT } from 'google-auth-library';"},{"note":"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.","symbol":"GoogleSpreadsheetWorksheet (type)","correct":"import type { GoogleSpreadsheetWorksheet } from 'google-spreadsheet';"}],"quickstart":{"code":"import { GoogleSpreadsheet } from 'google-spreadsheet';\nimport { JWT } from 'google-auth-library';\n\n// Initialize auth - use environment variables for security\n// process.env.GOOGLE_PRIVATE_KEY should have '\\n' replaced with '\\\\n' if set as env var\nconst serviceAccountAuth = new JWT({\n  email: process.env.GOOGLE_SERVICE_ACCOUNT_EMAIL ?? '',\n  key: process.env.GOOGLE_PRIVATE_KEY?.replace(/\\\\n/g, '\\n') ?? '', // Handle escaped newlines\n  scopes: ['https://www.googleapis.com/auth/spreadsheets'],\n});\n\nasync function main() {\n  const doc = new GoogleSpreadsheet(process.env.GOOGLE_SHEET_ID ?? '', serviceAccountAuth);\n\n  await doc.loadInfo(); // loads document properties and worksheets\n  console.log('Document title:', doc.title);\n  await doc.updateProperties({ title: 'Renamed Doc via API' });\n  console.log('Updated document title to:', doc.title);\n\n  const sheet = doc.sheetsByIndex[0]; // Access the first sheet\n  console.log('First sheet title:', sheet.title);\n  console.log('First sheet row count:', sheet.rowCount);\n\n  // Adding and removing a new sheet\n  const newSheet = await doc.addSheet({ title: 'Another Sheet ' + Date.now() });\n  console.log('Added new sheet:', newSheet.title);\n  await newSheet.delete();\n  console.log('Deleted the new sheet.');\n}\n\n// Run the main function (or wrap in an IIFE if top-level await is not supported)\nmain().catch(console.error);","lang":"typescript","description":"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."},"warnings":[{"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.","message":"Version 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.","severity":"breaking","affected_versions":">=5.0.0"},{"fix":"Replace calls to `doc.useServiceAccountAuth()` with creating an authenticated client from `google-auth-library` and passing it to `new GoogleSpreadsheet(id, authClient)`.","message":"Direct 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.","severity":"deprecated","affected_versions":">=4.1.1"},{"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 */ })();`.","message":"The 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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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`.","message":"The 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.","severity":"breaking","affected_versions":">=5.0.0"},{"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.","message":"When 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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"Prior 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`.","severity":"gotcha","affected_versions":"<5.2.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"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.","cause":"Attempting to use CommonJS `require()` syntax (`const { GoogleSpreadsheet } = require('google-spreadsheet');`) in an environment that expects ES modules, or with an incompatible module configuration.","error":"TypeError: GoogleSpreadsheet is not a constructor"},{"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.","cause":"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.","error":"Error: Missing credentials for 'JWT' (or similar 'credential.private_key should be a string' error)"},{"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.","cause":"The service account or API key used lacks the necessary permissions to access the specific Google Sheet or the Google Sheets API itself.","error":"Google API error: The caller does not have permission"},{"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.","cause":"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`.","error":"(node:...) UnhandledPromiseRejectionWarning: TypeError: Cannot read properties of undefined (reading 'loadInfo')"}],"ecosystem":"npm"}