{"id":13432949,"url":"https://github.com/theoephraim/node-google-spreadsheet","last_synced_at":"2026-06-04T00:00:18.247Z","repository":{"id":7242644,"uuid":"8552709","full_name":"theoephraim/node-google-spreadsheet","owner":"theoephraim","description":"Google Sheets API wrapper for Javascript / Typescript","archived":false,"fork":false,"pushed_at":"2026-06-03T22:07:53.000Z","size":1646,"stargazers_count":2485,"open_issues_count":39,"forks_count":390,"subscribers_count":27,"default_branch":"main","last_synced_at":"2026-06-03T23:13:54.966Z","etag":null,"topics":["google","google-sheets","google-sheets-api-v4","google-spreadsheets","nodejs","typescript"],"latest_commit_sha":null,"homepage":"https://theoephraim.github.io/node-google-spreadsheet","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/theoephraim.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":["theoephraim"],"custom":["https://buymeacoffee.com/theo.dmno"]}},"created_at":"2013-03-04T09:53:48.000Z","updated_at":"2026-06-03T22:07:12.000Z","dependencies_parsed_at":"2023-01-13T14:19:08.849Z","dependency_job_id":"4b026257-1f9c-4201-99b1-ac25eb66292f","html_url":"https://github.com/theoephraim/node-google-spreadsheet","commit_stats":{"total_commits":271,"total_committers":68,"mean_commits":3.985294117647059,"dds":0.6494464944649446,"last_synced_commit":"ae132d79764d65c35a0160609f1861304816837f"},"previous_names":["theoephraim/node-google-spreadsheets"],"tags_count":58,"template":false,"template_full_name":null,"purl":"pkg:github/theoephraim/node-google-spreadsheet","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/theoephraim%2Fnode-google-spreadsheet","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/theoephraim%2Fnode-google-spreadsheet/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/theoephraim%2Fnode-google-spreadsheet/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/theoephraim%2Fnode-google-spreadsheet/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/theoephraim","download_url":"https://codeload.github.com/theoephraim/node-google-spreadsheet/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/theoephraim%2Fnode-google-spreadsheet/sbom","scorecard":{"id":879515,"data":{"date":"2025-08-11","repo":{"name":"github.com/theoephraim/node-google-spreadsheet","commit":"f05799b64682e907aca79f1f9c956559d171d729"},"scorecard":{"version":"v5.2.1-40-gf6ed084d","commit":"f6ed084d17c9236477efd66e5b258b9d4cc7b389"},"score":3.5,"checks":[{"name":"Code-Review","score":1,"reason":"Found 3/29 approved changesets -- score normalized to 1","details":null,"documentation":{"short":"Determines if the project requires human code review before pull requests (aka merge requests) are merged.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#code-review"}},{"name":"Dangerous-Workflow","score":10,"reason":"no dangerous workflow patterns detected","details":null,"documentation":{"short":"Determines if the project's GitHub Action workflows avoid dangerous patterns.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#dangerous-workflow"}},{"name":"Packaging","score":-1,"reason":"packaging workflow not detected","details":["Warn: no GitHub/GitLab publishing workflow detected."],"documentation":{"short":"Determines if the project is published as a package that others can easily download, install, easily update, and uninstall.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#packaging"}},{"name":"Token-Permissions","score":0,"reason":"detected GitHub workflow tokens with excessive permissions","details":["Warn: no topLevel permission defined: .github/workflows/ci.yml:1","Info: no jobLevel write permissions found"],"documentation":{"short":"Determines if the project's workflows follow the principle of least privilege.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#token-permissions"}},{"name":"Maintained","score":10,"reason":"13 commit(s) and 14 issue activity found in the last 90 days -- score normalized to 10","details":null,"documentation":{"short":"Determines if the project is \"actively maintained\".","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#maintained"}},{"name":"Binary-Artifacts","score":10,"reason":"no binaries found in the repo","details":null,"documentation":{"short":"Determines if the project has generated executable (binary) artifacts in the source repository.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#binary-artifacts"}},{"name":"Pinned-Dependencies","score":0,"reason":"dependency not pinned by hash detected -- score normalized to 0","details":["Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/ci.yml:24: update your workflow using https://app.stepsecurity.io/secureworkflow/theoephraim/node-google-spreadsheet/ci.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/ci.yml:27: update your workflow using https://app.stepsecurity.io/secureworkflow/theoephraim/node-google-spreadsheet/ci.yml/main?enable=pin","Warn: third-party GitHubAction not pinned by hash: .github/workflows/ci.yml:31: update your workflow using https://app.stepsecurity.io/secureworkflow/theoephraim/node-google-spreadsheet/ci.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/ci.yml:42: update your workflow using https://app.stepsecurity.io/secureworkflow/theoephraim/node-google-spreadsheet/ci.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/ci.yml:67: update your workflow using https://app.stepsecurity.io/secureworkflow/theoephraim/node-google-spreadsheet/ci.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/ci.yml:72: update your workflow using https://app.stepsecurity.io/secureworkflow/theoephraim/node-google-spreadsheet/ci.yml/main?enable=pin","Info:   0 out of   5 GitHub-owned GitHubAction dependencies pinned","Info:   0 out of   1 third-party GitHubAction dependencies pinned"],"documentation":{"short":"Determines if the project has declared and pinned the dependencies of its build process.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#pinned-dependencies"}},{"name":"CII-Best-Practices","score":0,"reason":"no effort to earn an OpenSSF best practices badge detected","details":null,"documentation":{"short":"Determines if the project has an OpenSSF (formerly CII) Best Practices Badge.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#cii-best-practices"}},{"name":"Security-Policy","score":0,"reason":"security policy file not detected","details":["Warn: no security policy file detected","Warn: no security file to analyze","Warn: no security file to analyze","Warn: no security file to analyze"],"documentation":{"short":"Determines if the project has published a security policy.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#security-policy"}},{"name":"License","score":10,"reason":"license file detected","details":["Info: project has a license file: LICENSE:0","Info: FSF or OSI recognized license: MIT License: LICENSE:0"],"documentation":{"short":"Determines if the project has defined a license.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#license"}},{"name":"Fuzzing","score":0,"reason":"project is not fuzzed","details":["Warn: no fuzzer integrations found"],"documentation":{"short":"Determines if the project uses fuzzing.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#fuzzing"}},{"name":"Signed-Releases","score":-1,"reason":"no releases found","details":null,"documentation":{"short":"Determines if the project cryptographically signs release artifacts.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#signed-releases"}},{"name":"Branch-Protection","score":0,"reason":"branch protection not enabled on development/release branches","details":["Warn: branch protection not enabled for branch 'main'"],"documentation":{"short":"Determines if the default and release branches are protected with GitHub's branch protection settings.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#branch-protection"}},{"name":"SAST","score":0,"reason":"SAST tool is not run on all commits -- score normalized to 0","details":["Warn: 0 commits out of 8 are checked with a SAST tool"],"documentation":{"short":"Determines if the project uses static code analysis.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#sast"}},{"name":"Vulnerabilities","score":0,"reason":"22 existing vulnerabilities detected","details":["Warn: Project is vulnerable to: GHSA-v6h2-p8h4-qcjw","Warn: Project is vulnerable to: GHSA-67mh-4wv8-2f99","Warn: Project is vulnerable to: GHSA-pfrx-2q88-qq97","Warn: Project is vulnerable to: GHSA-4r62-v4vq-hr96","Warn: Project is vulnerable to: GHSA-5v2h-r2cx-5xgj","Warn: Project is vulnerable to: GHSA-rrrm-qjm4-v8hf","Warn: Project is vulnerable to: GHSA-mwcw-c2x4-8c55","Warn: Project is vulnerable to: GHSA-x7hr-w5r2-h6wg","Warn: Project is vulnerable to: GHSA-gcx4-mw62-g8wm","Warn: Project is vulnerable to: GHSA-c2qf-rxjj-qqgw","Warn: Project is vulnerable to: GHSA-m6fv-jmcg-4jfg","Warn: Project is vulnerable to: GHSA-cm22-4g7w-348p","Warn: Project is vulnerable to: GHSA-52f5-9888-hmc6","Warn: Project is vulnerable to: GHSA-64vr-g452-qvp3","Warn: Project is vulnerable to: GHSA-9cwx-2883-4wfx","Warn: Project is vulnerable to: GHSA-vg6x-rcgg-rjx6","Warn: Project is vulnerable to: GHSA-x574-m823-4x7w","Warn: Project is vulnerable to: GHSA-4r4m-qw57-chr8","Warn: Project is vulnerable to: GHSA-xcj6-pq6g-qj4x","Warn: Project is vulnerable to: GHSA-356w-63v5-8wf4","Warn: Project is vulnerable to: GHSA-859w-5945-r5v3","Warn: Project is vulnerable to: GHSA-3h5v-q93c-6h6q"],"documentation":{"short":"Determines if the project has open, known unfixed vulnerabilities.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#vulnerabilities"}}]},"last_synced_at":"2025-08-24T07:32:42.889Z","repository_id":7242644,"created_at":"2025-08-24T07:32:42.889Z","updated_at":"2025-08-24T07:32:42.889Z"},"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33884734,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-03T02:00:06.370Z","response_time":59,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["google","google-sheets","google-sheets-api-v4","google-spreadsheets","nodejs","typescript"],"created_at":"2024-07-31T02:01:18.907Z","updated_at":"2026-06-04T00:00:18.198Z","avatar_url":"https://github.com/theoephraim.png","language":"TypeScript","funding_links":["https://github.com/sponsors/theoephraim","https://buymeacoffee.com/theo.dmno","https://paypal.me/theoephraim"],"categories":["JavaScript","TypeScript"],"sub_categories":[],"readme":"# google-spreadsheet\n\n\u003e The most popular [Google Sheets API](https://developers.google.com/sheets/api/guides/concepts) wrapper for javascript / typescript\n\n\u003ca href=\"https://varlock.dev?ref=gsheets\"\u003e\u003cimg\n  src=\"https://varlock-pixel-art.dmno.workers.dev/characters/warlock1.gif\"\n  alt=\"wizard pixel art\"\n/\u003e\u003c/a\u003e\n\u003ca href=\"https://varlock.dev?ref=gsheets\"\u003e\u003cimg\n  src=\"https://varlock-pixel-art.dmno.workers.dev/other/github-gsheets-banner.png\"\n  alt=\"varlock banner\"\n/\u003e\u003c/a\u003e\n\n[![NPM version](https://img.shields.io/npm/v/google-spreadsheet)](https://www.npmjs.com/package/google-spreadsheet)\n[![CI status](https://github.com/theoephraim/node-google-spreadsheet/actions/workflows/ci.yml/badge.svg)](https://github.com/theoephraim/node-google-spreadsheet/actions/workflows/ci.yml)\n[![Known Vulnerabilities](https://snyk.io/test/github/theoephraim/node-google-spreadsheet/badge.svg?targetFile=package.json)](https://snyk.io/test/github/theoephraim/node-google-spreadsheet?targetFile=package.json)\n[![NPM](https://img.shields.io/npm/dw/google-spreadsheet)](https://www.npmtrends.com/google-spreadsheet)\n\n- multiple auth options (via [google-auth-library](https://www.npmjs.com/package/google-auth-library)) - service account, OAuth, API key, ADC, etc\n- cell-based API - read, write, bulk-updates, formatting\n- row-based API - read, update, delete (based on the old v3 row-based calls)\n- managing worksheets - add, remove, resize, update properties (ex: title), duplicate to same or other document\n- managing docs - create new doc, delete doc, basic sharing/permissions\n- export - download sheet/docs in various formats\n- automatic retries with exponential backoff for failed/rate-limited requests (powered by [ky](https://github.com/sindresorhus/ky), [customizable](https://theoephraim.github.io/node-google-spreadsheet/#/classes/google-spreadsheet#fn-newGoogleSpreadsheet))\n\n**Docs site -**\nFull docs available at [https://theoephraim.github.io/node-google-spreadsheet](https://theoephraim.github.io/node-google-spreadsheet)\n\n---\n\n\u003e 🌈 **Installation** - `npm i google-spreadsheet`\u003cbr/\u003e(or `pnpm`/`yarn`/`bun`/etc...)\n\n## Examples\n\n_The following examples are meant to give you an idea of just some of the things you can do_\n\n\u003e **IMPORTANT NOTE** - To keep the examples concise, I'm calling await [at the top level](https://v8.dev/features/top-level-await) which is not allowed in some older versions of node. If you need to call await in a script at the root level and your environment does not support it, you must instead wrap it in an async function like so:\n\n```javascript\n(async function () {\n  await someAsyncFunction();\n})();\n```\n\n### The Basics\n\n```js\nimport { GoogleSpreadsheet } from 'google-spreadsheet';\nimport { JWT } from 'google-auth-library';\n\n// Initialize auth - see https://theoephraim.github.io/node-google-spreadsheet/#/guides/authentication\nconst serviceAccountAuth = new JWT({\n  // env var values here are copied from service account credentials generated by google\n  // see \"Authentication\" section in docs for more info\n  email: process.env.GOOGLE_SERVICE_ACCOUNT_EMAIL,\n  key: process.env.GOOGLE_PRIVATE_KEY,\n  scopes: ['https://www.googleapis.com/auth/spreadsheets'],\n});\n\nconst doc = new GoogleSpreadsheet('\u003cthe sheet ID from the url\u003e', serviceAccountAuth);\n\nawait doc.loadInfo(); // loads document properties and worksheets\nconsole.log(doc.title);\nawait doc.updateProperties({ title: 'renamed doc' });\n\nconst sheet = doc.sheetsByIndex[0]; // or use `doc.sheetsById[id]` or `doc.sheetsByTitle[title]`\nconsole.log(sheet.title);\nconsole.log(sheet.rowCount);\n\n// adding / removing sheets\nconst newSheet = await doc.addSheet({ title: 'another sheet' });\nawait newSheet.delete();\n```\n\nMore info:\n\n- [GoogleSpreadsheet](https://theoephraim.github.io/node-google-spreadsheet/#/classes/google-spreadsheet)\n- [GoogleSpreadsheetWorksheet](https://theoephraim.github.io/node-google-spreadsheet/#/classes/google-spreadsheet-worksheet)\n- [Authentication](https://theoephraim.github.io/node-google-spreadsheet/#/guides/authentication)\n\n### Working with rows\n\n```js\n// if creating a new sheet, you can set the header row\nconst sheet = await doc.addSheet({ headerValues: ['name', 'email'] });\n\n// append rows\nconst larryRow = await sheet.addRow({ name: 'Larry Page', email: 'larry@google.com' });\nconst moreRows = await sheet.addRows([\n  { name: 'Sergey Brin', email: 'sergey@google.com' },\n  { name: 'Eric Schmidt', email: 'eric@google.com' },\n]);\n\n// read rows\nconst rows = await sheet.getRows(); // can pass in { limit, offset }\n\n// read/write row values\nconsole.log(rows[0].get('name')); // 'Larry Page'\nrows[1].set('email', 'sergey@abc.xyz'); // update a value\nrows[2].assign({ name: 'Sundar Pichai', email: 'sundar@google.com' }); // set multiple values\nawait rows[2].save(); // save updates on a row\nawait rows[2].delete(); // delete a row\n```\n\nRow methods support explicit TypeScript types for shape of the data\n\n```typescript\ntype UsersRowData = {\n  name: string;\n  email: string;\n  type?: 'admin' | 'user';\n};\nconst userRows = await sheet.getRows\u003cUsersRowData\u003e();\n\nuserRows[0].get('name'); // \u003c- TS is happy, knows it will be a string\nuserRows[0].get('badColumn'); // \u003c- will throw a type error\n```\n\nMore info:\n\n- [GoogleSpreadsheetWorksheet \u003e Working With Rows](https://theoephraim.github.io/node-google-spreadsheet/#/classes/google-spreadsheet-worksheet#working-with-rows)\n- [GoogleSpreadsheetRow](https://theoephraim.github.io/node-google-spreadsheet/#/classes/google-spreadsheet-row)\n\n### Working with cells\n\n```js\nawait sheet.loadCells('A1:E10'); // loads range of cells into local cache - DOES NOT RETURN THE CELLS\nconsole.log(sheet.cellStats); // total cells, loaded, how many non-empty\nconst a1 = sheet.getCell(0, 0); // access cells using a zero-based index\nconst c6 = sheet.getCellByA1('C6'); // or A1 style notation\n// access everything about the cell\nconsole.log(a1.value);\nconsole.log(a1.formula);\nconsole.log(a1.formattedValue);\n// update the cell contents and formatting\na1.value = 123.456;\nc6.formula = '=A1';\na1.textFormat = { bold: true };\nc6.note = 'This is a note!';\nawait sheet.saveUpdatedCells(); // save all updates in one call\n```\n\nMore info:\n\n- [GoogleSpreadsheetWorksheet \u003e Working With Cells](https://theoephraim.github.io/node-google-spreadsheet/#/classes/google-spreadsheet-worksheet#working-with-cells)\n- [GoogleSpreadsheetCell](https://theoephraim.github.io/node-google-spreadsheet/#/classes/google-spreadsheet-cell)\n\n### Managing docs and sharing\n\n```js\nconst auth = new JWT({\n  email: process.env.GOOGLE_SERVICE_ACCOUNT_EMAIL,\n  key: process.env.GOOGLE_PRIVATE_KEY,\n  scopes: [\n    'https://www.googleapis.com/auth/spreadsheets',\n    // note that sharing-related calls require the google drive scope\n    'https://www.googleapis.com/auth/drive.file',\n  ],\n});\n\n// create a new doc\nconst newDoc = await GoogleSpreadsheet.createNewSpreadsheetDocument(auth, { title: 'new fancy doc' });\n\n// share with specific users, domains, or make public\nawait newDoc.share('someone.else@example.com');\nawait newDoc.share('mycorp.com');\nawait newDoc.setPublicAccessLevel('reader');\n\n// delete doc\nawait newDoc.delete();\n```\n\n## Why?\n\n\u003e **This module provides an intuitive wrapper around Google's API to simplify common interactions**\n\nWhile Google's v4 sheets API is much easier to use than v3 was, the official [googleapis npm module](https://www.npmjs.com/package/googleapis) is a giant autogenerated meta-tool that handles _every Google product_. The module and the API itself are awkward and the docs are pretty terrible, at least to get started.\n\n**In what situation should you use Google's API directly?**\u003cbr\u003e\nThis module makes trade-offs for simplicity of the interface.\nGoogle's API provides a mechanism to make many requests in parallel, so if speed and efficiency are extremely important to your use case, you may want to use their API directly. There are also many lesser-used features of their API that are not implemented here yet.\n\n## Support \u0026 Contributions\n\nThis module was written and is actively maintained by [Theo Ephraim](https://theoephraim.com).\n\n**Are you actively using this module for a commercial project? Want to help support it?**\u003cbr\u003e\n[Buy Theo a beer](https://paypal.me/theoephraim)\n\n### Sponsors\n\nNone yet - get in touch!\n\n### Contributing\n\nContributions are welcome, but please follow the existing conventions, use the linter, add relevant tests, and add relevant documentation.\n\nThe docs site is generated using [docsify](https://docsify.js.org). To preview and run locally so you can make edits, run `npm run docs:preview` and head to http://localhost:3000\nThe content lives in markdown files in the docs folder.\nThe package manager for this project is `bun`.\n\n## License\n\nThis project is released under the MIT license. Previously it was using the \"Unlicense\". TLDR do whatever you want with it.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftheoephraim%2Fnode-google-spreadsheet","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftheoephraim%2Fnode-google-spreadsheet","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftheoephraim%2Fnode-google-spreadsheet/lists"}