googleworkspace/apps-script-samples: what the sample repo actually contains

What problem the sample repository solves

Apps Script is a JavaScript runtime that lives inside Google's infrastructure, and the hard part of learning it is rarely the language. It is the shape of the surrounding objects: how a Calendar event is queried, how a Drive file listing is paged, how an add-on declares its homepage trigger. This repository exists to answer those questions with code you can open and run, organised by product rather than by concept. The top level is a list of directories, each one a Workspace surface: adminSDK, advanced, calendar, chat, classroom, data-studio, docs, drive, forms, forms-api, gmail, gmail-sentiment-analysis, mashups, people, picker, service, sheets, slides, solutions, tasks, templates, triggers, ui, utils, ai, apps-script and wasm.

The audience is developers who already know JavaScript and need the Google-specific parts. The README describes the repository as "Various sample code and projects for the Google Apps Script platform", and that wording is accurate: these are samples, not a framework. If you are looking for an npm package to add to a build, this is the wrong repository, and the package.json confirms it by setting "private": true.

How the samples are organised and what runs them

Each top-level directory is self-contained. The README pairs a product with one or more entry points, and those entries point at either a quickstart directory or a single file. Calendar offers calendar/quickstart for listing upcoming events and solutions/automations/vacation-calendar/Code.js for creating a vacation calendar. Drive has drive/quickstart for file and folder management and drive/activity for viewing Drive activity. Docs ships two add-ons, docs/cursorInspector and docs/translate. Slides ships slides/translate and slides/progress. Gmail covers gmail/sendingEmails and gmail/mailmerge. Smaller surfaces are represented too: people/quickstart for listing connections, tasks/quickstart and tasks/simpleTasks, forms for a notification add-on, sheets for managing Form responses and for menus and custom functions.

The toolchain is the part that surprises people. The repository is a pnpm workspace with a package.json that declares devDependencies on @biomejs/biome, @types/google-apps-script, @types/node, tsx and typescript, requires Node 20 or newer, and pins packageManager to [email protected]. Two scripts do the work. pnpm lint runs tsx .github/scripts/biome-gs.ts lint, which the README says will fix simple errors. pnpm check runs tsx .github/scripts/check-gs.ts, and the README explains that it validates .gs files by temporarily converting them to .js and running tsc, checking syntax and type issues against JSDoc annotations. That indirection is worth understanding: Apps Script files carry a .gs extension that TypeScript does not recognise, so the check script rewrites them on the fly rather than asking you to rename anything.

Installing the toolchain and running your first sample

There is nothing to install for the samples themselves. An Apps Script project is created in the browser or cloned with clasp, and the README links to the clasp guide at developers.google.com/apps-script/guides/clasp for clone, pull and push on the command line. What you install locally is the lint and type-check toolchain, which lives at the repository root.

Start by cloning the repository and installing dependencies with pnpm. The engines field requires Node 20 or newer, so check that first.

node --version
pnpm install

After installation, run the two checks the README documents. The lint script fixes simple formatting and style errors; the check script converts .gs to .js in a temporary step and runs tsc over the result.

pnpm lint
pnpm check

For a first real use, pick a quickstart rather than a solution. calendar/quickstart is the smallest useful example: it lists upcoming events, which means one OAuth scope and one API call, so failures are easy to attribute. Copy the files into a new Apps Script project, either through the browser editor or with clasp, and run the function that the quickstart names. The repository does not document a rollback path for the lint script, so if pnpm lint rewrites a sample in a way you did not want, restore the file from git.

Where the samples stop being useful

The repository is a set of examples, and examples are written to be read. Several entries are single files rather than projects: the vacation calendar is solutions/automations/vacation-calendar/Code.js, and the Data Studio connector is data-studio/build.gs with a companion data-studio/auth.gs. A single file gives you the logic but not the manifest, the deployment configuration or the trigger setup that a working add-on needs. You will be filling those in yourself.

The second limitation is verification. The pnpm check script validates syntax and JSDoc types, and pnpm lint fixes simple errors, but neither runs the code against a live Google account. Nothing in the repository tells you whether a given sample still matches the current API surface of the product it targets. The README does not document a compatibility matrix, a supported Apps Script runtime version, or a deprecation policy for individual samples.

There is also a licence detail worth noticing. The repository licence is Apache-2.0, while the package.json declares "license": "MIT". Both are permissive, and for copying a sample into your own project the practical difference is small, but the discrepancy is real and you should read LICENSE rather than the package.json field if the distinction matters to your organisation. This is not legal advice; check with whoever handles licensing where you work.

How this differs from clasp and from the Apps Script docs

The obvious alternative is clasp, the command-line tool the README itself points to for cloning, pulling and pushing Apps Script projects. The difference in approach is that clasp is a deployment tool and this repository is a content library. clasp gives you a way to move code between your machine and Google's servers; it does not give you a Calendar quickstart or a mail merge example. In practice you use both: clasp to manage the project, these samples as the code you push into it. The repository even links a codelab for clasp at g.co/codelabs/clasp.

The second alternative is the official Apps Script documentation at developers.google.com/apps-script, which the README names as the place to learn more. Documentation explains the API; this repository shows a working call site. When the two disagree, the documentation is the authority and the sample is the thing that has fallen behind. That is the correct order of trust, and it is why you should treat any sample here as a starting point to be checked rather than a specification.

Maintenance, licence and what it costs to keep up

The repository is not archived, and the last push was on 2026-07-30. That is recent enough that the toolchain reflects current practice: TypeScript 5.9, Biome 1.9.4, Node 20 as the floor, pnpm 10.15.1. There are no retrieved releases, so there is no versioned artefact to track and no changelog to read. Upgrade cost is therefore low in the conventional sense and high in an unconventional one: nothing breaks because nothing is versioned, but nothing tells you when a sample has drifted from the API it calls.

The devDependencies are pinned with caret ranges, so pnpm install will pull newer patch and minor versions of Biome, TypeScript and the Google Apps Script type definitions. The type definitions are the ones most likely to move, since they track the Apps Script runtime. If pnpm check starts failing after an install, that is the first place to look. Running the two scripts in CI is the cheapest way to notice drift, and the repository layout already supports it: the scripts live under .github/scripts, and the repository ships a .github directory.

On licence, Apache-2.0 at the repository level is permissive and includes an explicit patent grant. The MIT declaration in package.json is narrower in that respect. If you are copying sample code into a commercial product, read LICENSE and follow the attribution terms it sets out rather than relying on the package.json field.

Editorial conclusion

Adopt this repository if you learn Apps Script by reading working code, or if you want a starting point for a Calendar, Drive, Gmail or Classroom integration before writing your own. Do not adopt it as a dependency: there is no published package, no versioned API and no support commitment, and the package.json is marked private. Before you copy anything, open the subdirectory you care about, confirm which OAuth scopes its manifest requests, and run pnpm check so the .gs files are validated by tsc rather than trusted on sight.

Frequently asked questions

Official sources

1. googleworkspace/apps-script-samples on GitHub
2. Issues
3. License: Apache-2.0
4. Project website
5. README