Using in Projects

Add GasPackᵐ to an existing project

GasPackᵐ slots into any existing Apps Script project that uses clasp. You don't need to restructure your code — just drop in a manifest and start installing packages.

cd my-gas-project

Starting fresh instead? Skip to Start from a Template below.

Start from a template

gpm create project <name> scaffolds a new Apps Script project with GasPackᵐ wired in from the start — manifest, modules folder, build config, and (optionally) a clasp project created for you.

What you get

my-gas-app/
├── src/
│   └── Code.js          # Entry point with a sample main() function
├── modules/             # Your in-project modules go here
├── appsscript.json      # Apps Script manifest (scopes, timezone)
├── gpm.json             # GasPackᵐ manifest (dependencies, build config)
├── gaspack.json.js      # Build config (entry points, module wrapping)
├── package.json         # npm devDependencies for the build toolchain
├── .clasp.json          # clasp configuration (rootDir patched to build/)
├── .gitignore
└── README.md

Built-in template

The default template ships with a minimal Code.js that demonstrates how to read project metadata, list installed packages, and call into a versioned namespace. It's the smallest useful starting point — enough to clasp-push and see your project on Apps Script, nothing more.

Install Packages

Search the registry and install packages to add functionality to your project.

Search for packages

Find packages by name or keyword:

View package details

Get more information about a package before installing:

gpm info @user.gmail.com/sheet-utils

Install a package

Install a specific version

gpm install @user.gmail.com/sheet-utils --ver 1.1.0

Use Packages in Code

Packages expose their functions via namespaced globals. After building, you can call them directly in your Apps Script code.

Understanding namespaces

Each package module has a unique versioned namespace (like SHEET_UTILS_V1 or LOGGER_V2). The _Vx suffix matches the installed major version, so multiple major versions of a package can coexist in a single project without colliding. Check the package documentation to find its namespace.

Example usage

Assuming you ran gpm install @user.gmail.com/sheet-utils and got sheet-utils@1.2.0, the runtime namespace is SHEET_UTILS_V1:

// Using the SHEET_UTILS_V1 namespace from sheet-utils@1.2.0
function processData() {
  const sheet = SpreadsheetApp.getActiveSheet();
  const data = sheet.getDataRange().getValues();

  // Call package functions via versioned namespace
  const formatted = SHEET_UTILS_V1.formatCurrency(data[0][1]);
  const cleaned = SHEET_UTILS_V1.trimWhitespace(data[0][0]);

  Logger.log(formatted, cleaned);
}

Multiple packages

You can use multiple packages together — each keeps its own versioned namespace:

function runJob() {
  // Using logger@2.x
  LOGGER_V2.info('Starting job...');

  // Using sheet-utils@1.x
  const data = SHEET_UTILS_V1.getSheetData('Sheet1');

  // Using cache-utils@1.x
  CACHE_V1.set('lastRun', new Date().toISOString());

  LOGGER_V2.info('Job complete');
}

Build & Deploy

Bundle your project with all dependencies, then push to Google Apps Script.

Build your project

Check for updates

See if newer versions are available:

gpm build --check-updates

Push to Apps Script

Use clasp to deploy your built project:

clasp push

gpm build && clasp push

Build options

Manage Dependencies

View, update, and remove packages from your project.

# List all packages
gpm list

# Show detailed info
gpm list --verbose

# Show module exports
gpm list --exports

# Update all packages
gpm update

# Update specific package
gpm update @user.gmail.com/logger

gpm uninstall @user.gmail.com/logger

gpm audit

Install all dependencies

When cloning a project or setting up on a new machine, install all dependencies from gpm.json:

Use a local source for a dependency

By default, dependencies in your project come from the GasPackᵐ Exchange. gpm link lets you substitute a local source tree for any dependency — useful when you need to work with code that isn't yet (or isn't quite) on the registry.

When you'd link in a project

• Trying a candidate version. A maintainer has a fix on their branch. Clone their fork locally, run gpm link inside it to register the package, then gpm link @scope/pkg in your project to consume that local version instead of the registry one.
• Working from a fork. You maintain a fork of a package with patches that haven't been upstreamed. Point your project at the fork until upstream catches up.
• Monorepo siblings. Your project and one of its dependencies live in the same tree. Link them so the project's build picks up local source.
• Patching during an incident. A dependency has a bug and upstream isn't responsive. Patch a local copy and link until the fix ships.

Using it

Authoring a package and feeding it into a test project from the publisher side? See Creating Packages → Linking for the author-focused workflow.

Run your project locally Planned

gpm init-local will let you execute your Apps Script project from Node — your own code plus its dependencies — using the gas-fakes emulation layer. No clasp push cycle between every edit; iterate against the same GAS APIs you'd see in production.

Why this matters for projects

For consumers (you), local execution closes a real feedback gap. Right now, testing means gpm build → clasp push → run the function from the Apps Script editor → check logs. That's three steps and a network round-trip per change. With gas-fakes plugged in, the same script runs from node in milliseconds — useful for both rapid iteration and CI-friendly automated tests.

External references

• gas-fakes — Node.js emulation layer for Apps Script (MIT, by Bruce McPherson). Translates GAS service calls into Google Workspace API requests.
• apps-script-engine-template — a community-maintained project template (webpack, environments, Jest, ESLint) that pairs well with the gas-fakes local-execution pattern.