The Complete Guide to Google Apps Script Extensions

If you've ever wanted to add a custom menu to Google Sheets, a sidebar to Gmail, or a slash-command to Google Docs, you've already brushed up against Google Apps Script extensions. They're the surface area that turns Apps Script from "a scripting language hidden behind Tools → Apps Script" into a real distribution channel — one that puts your code in front of Workspace's three billion users.

This guide covers what extensions actually are (the terminology is messier than it should be), the three main flavors, how to build and publish one, and the production-grade tools the community uses to ship faster.

The terminology problem

"Apps Script extension" is a catch-all. In practice it refers to one of three distinct things:

1. Workspace Add-ons — the official Google-blessed way to extend Gmail, Sheets, Docs, Slides, Drive, and Calendar with sidebars, cards, and custom menus. These ship through the Google Workspace Marketplace and run on Apps Script's CardService API.
2. Editor add-ons (legacy) — the older API that only worked inside the Google Sheets/Docs/Slides editor. Google is migrating these to Workspace Add-ons; you'll still see "Editor add-on" in old tutorials, but new builds should target Workspace Add-ons.
3. Chrome extensions for the Apps Script editor — browser extensions that improve the script.google.com IDE itself: autocomplete, dark mode, linting, deployment helpers. These aren't Apps Script code at all — they're regular Chrome extensions that augment your dev experience.

When someone says "I built an Apps Script extension," they usually mean #1 (a Workspace Add-on) or #3 (a Chrome extension for the editor). Browse the Extensions category on this directory and you'll see both.

When to build a Workspace Add-on

Workspace Add-ons are the right choice when:

• You want to distribute your tool to non-developers (your spouse, your team, the wider Workspace ecosystem)
• The functionality lives inside Gmail / Sheets / Docs as a sidebar, card, or menu item
• You need OAuth into the user's Google account
• You want to charge money (Marketplace supports paid listings)

They're the wrong choice when:

• You want a standalone web app (use a deployed Apps Script Web App instead)
• Your tool needs to run on a schedule without user interaction (use a time-driven trigger)
• You don't want Google's review process gating your releases

Building one: the minimum viable add-on

The core of any Workspace Add-on is a manifest (in appsscript.json) plus event-handler functions that return Card objects. The smallest possible Gmail add-on is about 30 lines:

// Code.gs
function buildHomepage() {
  const card = CardService.newCardBuilder()
    .setHeader(CardService.newCardHeader().setTitle("Hello"))
    .addSection(
      CardService.newCardSection().addWidget(
        CardService.newTextParagraph().setText("This is my add-on.")
      )
    )
    .build()
  return [card]
}

// appsscript.json
{
  "addOns": {
    "common": {
      "name": "My Add-on",
      "logoUrl": "https://example.com/logo.png"
    },
    "gmail": {
      "homepageTrigger": { "runFunction": "buildHomepage" }
    }
  },
  "oauthScopes": ["https://www.googleapis.com/auth/gmail.addons.execute"]
}

Push that with clasp, deploy as a test add-on, and you'll see it in your Gmail sidebar within seconds. The full Workspace Add-on docs are at developers.google.com/workspace/add-ons.

The development workflow that doesn't make you cry

The Apps Script editor (script.google.com) is fine for trying things out, but it's not where you want to build a real add-on. The community workflow looks like this:

1. Code locally with clasp + TypeScript. The boilerplates in our directory get you to a TypeScript project pushing to Apps Script in about two minutes. You write .ts files, clasp push compiles and uploads.
2. Version control with Git. Apps Script projects are just files. Commit them. Push to GitHub. The same review/PR flow as any other project.
3. Lint and test before deploy. There are several libraries for assertion-style testing inside Apps Script, plus you can run vanilla Node-based unit tests against the parts of your code that don't depend on Workspace APIs.
4. Deploy with versioning. clasp deploy creates immutable versions, so rolling back is a one-command operation.

If you're starting from scratch, pick a boilerplate that matches your target surface (Gmail add-on, Sheets add-on, Web App, etc.) and clone it. You'll save a day of YAML wrestling.

Publishing to the Workspace Marketplace

Once your add-on works, publishing to the Marketplace is roughly:

1. Create an OAuth consent screen for your GCP project
2. Submit for OAuth verification if you use sensitive scopes (this can take 1-6 weeks)
3. Create a Marketplace SDK listing with screenshots, descriptions, and a privacy policy
4. Submit for review

The OAuth verification step is the painful one. Plan for it. If your add-on doesn't strictly need a sensitive scope, dropping it can shave weeks off the timeline.

Chrome extensions for the editor

The other kind of "Apps Script extension" — Chrome extensions that improve the IDE — are a different beast entirely. They don't go through Google review (just the Chrome Web Store's much faster process) and they can do things the official editor will never do: better autocomplete, real diff views, structured logging, fast project switching.

The best ones in the community are listed in our Extensions category. If you're shipping Apps Script code daily, installing two or three of these will save you hours per week. The IDE's built-in features are deliberately minimal — extensions fill the gap.

Common pitfalls

A few things that catch every Apps Script developer at least once:

• Quota limits. UrlFetchApp has a 20,000 calls/day quota on consumer accounts. If your add-on hits external APIs in a loop, you will exhaust this. Cache aggressively with CacheService or PropertiesService.
• Execution time cap. Apps Script kills any execution running longer than 6 minutes (30 for Workspace accounts). Long-running jobs need to chunk work and re-trigger themselves.
• OAuth scope creep. Every sensitive scope you add slows verification and scares users at the consent screen. Use the narrowest scope that works.
• Logger.log vs console.log. They behave differently in different contexts. Use console.log — it integrates with Cloud Logging if you wire it up.

Where to go next

• Browse the Extensions directory to see what the community has built
• If you're starting a new project, grab a boilerplate
• For utilities you'll import into your project, check the Libraries
• For full open-source examples to learn from, browse GitHub repos

Workspace Add-ons are a small but growing distribution channel — about 5,000 published add-ons at the time of writing, against 3 billion Workspace users. The market is real, the platform is stable, and the tooling has gotten substantially better in the last two years. There's never been a better time to ship one.