Artist: Daryna Mikhailenko

English | Українська | Русский | Deutsch | Français | Español | Português | 日本語 | 中文

Boot Framework for Google Apps Script™

Introduction

Boot.gs is a lightweight framework designed to help build structured Google Apps Script applications. It aims to bring familiar development patterns, such as decorators and dependency injection, to the Apps Script environment to aid in code organization.

Your controllers stay environment-agnostic: the same code handles doGet/doPost web requests, google.script.run calls from sidebars and dialogs, and Google Workspace events such as onOpen or onEdit.

Features

• Decorator-based Routing: Intuitive mapping of HTTP and Apps Script events (GET, POST, etc.).
• Spring Boot & NestJS Patterns: Familiar decorators like @RequestMapping, @RestController, @ResponseBody, and the ResponseEntity class.
• Flexible Responses: Full control over HTTP status codes, headers, and MIME types using ResponseEntity.
• Validation: Declarative parameter validation using Spring Boot-style decorators like @Min, @Max, @Email, etc.
• Pipes & Validation: Transform and validate incoming data with @UsePipes and built-in pipes (e.g., ParseNumberPipe).
• Global Error Handling: Centralized exception management using @ControllerAdvice and @ExceptionHandler.
• Dependency Injection: Fully-featured DI for better decoupling and testability.
• Type Safety: Built with TypeScript for a robust development experience.
• Modern Architecture: Inspired by frameworks like NestJS and Spring Boot.

Requirements

• A Google Apps Script project on the V8 runtime, typically managed locally with clasp.
• TypeScript with experimentalDecorators and emitDecoratorMetadata enabled in tsconfig.json.
• Node.js >=22.14.0 and npm for installing and building.

Installation

Install the framework via npm:

npm install bootgs

Quick Start

1. Define a Controller

Create a class to handle your application's logic. Decorators map methods to specific endpoints or events.

import {Get, RestController} from "bootgs";

@RestController("api/sheet")
export class SheetController {
    /**
     * Handles GET requests to /api/sheet/active-range
     */
    @Get("active-range")
    getActiveRange(): string {
        return "This action returns the active sheet range.";
    }
}

2. Initialize the Application

Create an App instance and delegate the standard Apps Script entry points to it, so the framework can intercept and route incoming events.

import {App} from "bootgs";
import {SheetController} from "./SheetController";

/**
 * Global entry point for GET requests.
 */
export function doGet(event: GoogleAppsScript.Events.DoGet) {
    const app = App.create({
        controllers: [SheetController]
    });
    return app.doGet(event);
}

The full walkthrough, including doPost and the asynchronous AsyncApp, is in the Quick Start guide.

Documentation

• Quick Start: synchronous App and asynchronous AsyncApp setup.
• Calling the API (Virtual Transport Layer): request parameters, MIME types, google.script.run and Web App URL calls, response wrapping.
• Decorators: class, method and parameter decorators, validation and built-in pipes.
• Controlling the Response: ResponseEntity and @ResponseBody.
• Advanced Examples: pipes and global error handling.
• AI Agent Skills: the full skill list and installation options.
• Boot.gs vs Spring Boot vs NestJS: architecture comparison.

AI Agent Skills

Working with an AI coding agent (Claude Code, Gemini CLI, Cursor, etc.)? The bootgs/skills repository provides Agent Skills that teach it how to scaffold, structure, and validate Boot.gs applications, plus framework-agnostic skills for Google Apps Script development.

/plugin marketplace add bootgs/skills
/plugin install bootgs@bootgs-skills

See AI Agent Skills for the full list and for Gemini CLI and npx skills installation.

Recommended

Tip

For enhanced development with Google Apps Script, we recommend using @bootgs/utils, a collection of utility functions and classes that complement this framework.

Contributors

Contributing

We welcome contributions! Please see our Contributing Guidelines for details on our code of conduct, and the process for submitting pull requests. To report a vulnerability, follow the Security Policy.

Roadmap

Check out our Roadmap to see what we have planned for future releases.

Changelog

For a detailed list of changes and updates, please refer to the CHANGELOG.

Support

Questions and bug reports go to GitHub Issues. If the project helps you, you can support it via GitHub Sponsors or Buy Me a Coffee.

License

This project is licensed under the Apache-2.0 License.

---

⭐ Like this project? Give it a star on GitHub!