Creating Packages

Create a Package

Packages are reusable code libraries that can be published to the registry and installed by others.

{
  "name": "my-utils",
  "version": "1.0.0",
  "description": "Utility functions for Google Apps Script",
  "keywords": ["utility", "helpers"],
  "license": "MIT"
}

/**
 * Formats a number as currency
 * @param {number} value - The value to format
 * @returns {string} Formatted currency string
 */
export function formatCurrency(value) {
  return '$' + value.toFixed(2);
}

/**
 * Removes leading/trailing whitespace
 * @param {string} str - The string to trim
 * @returns {string} Trimmed string
 */
export function trimWhitespace(str) {
  return str.trim();
}

Package Structure

A package contains one or more modules. Each module has its own namespace and exports.

Directory layout

my-package/
├── gpm.json              # Package manifest
├── package.json          # NPM config (optional)
├── README.md             # Documentation
└── src/
    ├── base/             # Default module
    │   └── index.js
    ├── utils/            # Additional module
    │   └── index.js
    └── helpers/          # Another module
        └── index.js

Adding modules

Add more modules to your package:

Module namespaces

Each module has a namespace that users will use to access its exports. Namespaces should be unique and descriptive:

Exports

Use ES module exports in your code:

// Named exports (recommended)
export function formatDate(date) {
  return date.toLocaleDateString();
}

export function formatTime(date) {
  return date.toLocaleTimeString();
}

// Export constants
export const DATE_FORMAT = 'YYYY-MM-DD';

Scopes & Services

Configure OAuth scopes and Advanced Services that your package requires. These are automatically added to users' projects when they install your package.

Add scopes and services

Use the interactive gpm add command:

Select modules and toggle the scopes you need:

View configured scopes

Remove scopes

gpm remove

Common OAuth scopes

Module Dependencies

If your modules reference namespaces from other packages at runtime, declare those dependencies. This enables selective installation — consumers only download the specific modules they need.

Declare dependencies

Use gpm dep add to declare what each module depends on:

You can also resolve by namespace if you know the GAS global name:

gpm dep add fetch --dep-ns QUOTA_V1

Detect missing dependencies

Scan your compiled code to find namespace references you haven't declared:

Build with validation

Use --strict-deps to ensure all dependencies are properly declared:

gpm build --strict-deps

Cross-package dependencies that can't be resolved locally (because the dependency package isn't installed in your package directory) are noted as informational — they'll be resolved by the registry when a consumer installs your package.

Dependency commands

Linking

gpm link substitutes a live source tree for what would otherwise be a registry-installed copy. When a consumer project depends on a linked package, every build in the consumer picks up your latest edits directly — no publish, no install.

What linking is for

• Iterating on your own package. Edit your package source, run gpm build in the consumer, and the new code is in the bundle. No publish/install cycle between every change.
• Pre-release validation. Try a candidate version against a real consumer before publishing to the Exchange — and avoid burning a version number on something you might revise.
• Monorepo cross-package work. If two of your packages reference each other and both live in your tree, link them so the build picks up local source.
• Working from a fork. Point a consumer at your fork of someone else's package instead of the registry version.

How it works

Two modes:

Walkthrough

gpm build && clasp push

Layout on disk

~/development/
├── my-package/              # Source you're authoring
│   ├── src/
│   │   └── base/
│   │       └── index.js
│   └── gpm.json
│
└── test-project/            # Consumer that depends on it
    ├── src/
    │   └── Code.js
    ├── gpm.json             # records "@you.gmail.com/my-package": "link:..."
    └── gpm_modules/
        └── @you.gmail.com/
            └── my-package → ~/development/my-package (linked)

~/.gpm/links/                # global "packages I'm developing" registry
└── @you.gmail.com-my-package → ~/development/my-package

Local execution Planned

The companion to gpm link is gpm init-local — a one-time, per-project setup that wires up the gas-fakes runtime so you can execute Apps Script code from Node, without clasp push on every iteration.

Two execution patterns to support

Reading existing community work (see references below), gpm init-local should accommodate both styles. They serve different audiences:

• Library mode. Import gas-fakes once at the top of a Node entry, import your modules, call them directly. Best for automated tests, Vitest harnesses, and any multi-call flow. Default scaffold target.
• CLI mode. Wrap each module function as a small script using gas-fakes' function myFunction(args) convention, invoke via gas-fakes -f tools/<name>.js -a '<JSON>'. Best for one-shots, shell-driven workflows, and exposing modules as MCP tools. A potential gpm init-local --tools mode.

Reference for implementers

Starting points for whoever picks this up:

• gas-fakes — the underlying Node.js emulation layer (MIT, Bruce McPherson). Relevant CLI flags: -s "<code>" inline, -f <script.js> file mode, -x execute, -a '<JSON>' args (received as args inside the script), -w <docId> bound-document context.
• Next-Level Google Apps Script Development — Kanshi Tanaike's worked example of an MCP server that wraps GAS scripts as tools via the gas-fakes CLI. The pattern suggests an interesting follow-on: gpm modules as MCP tools, where each module function is exposed to AI agents through a thin gas-fakes-CLI wrapper. Worth evaluating after gpm init-local ships.

Publishing

Share your package with the world or keep it private for your own projects.

Pre-publish checklist

• gpm build completes without errors
• All exports work correctly in Apps Script
• gpm verify passes security checks
• Version number is correct in gpm.json

Dry run

Preview what will be published:

Publish

Access levels

Version updates

Bump the module version before publishing updates. Package version is auto-calculated.

# Patch: 1.0.0 → 1.0.1 (bug fixes)
gpm bump base patch

# Minor: 1.0.0 → 1.1.0 (new features)
gpm bump base minor

# Major: 1.0.0 → 2.0.0 (breaking changes — namespace changes!)
gpm bump base major

# Then publish
gpm publish

Security scanning

All packages are automatically scanned for security issues before publishing. Packages with critical vulnerabilities (grade D or F) will be rejected.