Artist: Daryna Mikhailenko

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.

Install the framework via npm:

npm install bootgs

Create a class to handle your application's logic. Decorators make it easy to 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.";
    }
}

Bootstrap your application by creating an App instance and delegating the standard Apps Script entry points (doGet, doPost) to it.

Use App for synchronous execution:

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);
}

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

Use AsyncApp when you need to handle asynchronous operations (e.g., UrlFetchApp promises or other async tasks) in your controllers:

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

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

/**
 * Global entry point for POST requests.
 */
export async function doPost(event: GoogleAppsScript.Events.DoPost) {
    const app = AsyncApp.create({
        controllers: [SheetController]
    });
    return await app.doPost(event);
}

• 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.

The primary goal of Boot.gs is to ensure your code remains environment-agnostic. It should function identically whether it’s triggered via doGet/doPost or google.script.run.

Since Google Apps Script (GAS) has certain constraints on headers and routing, the framework implements a Virtual Transport Layer. This layer "tucks" your request metadata (like the HTTP method and path) into parameters so the framework handles the routing for you seamlessly.

To simulate a standard HTTP request, you pass these key parameters to the framework:

• method: Simulates the HTTP method (GET, POST, PUT, DELETE, etc.).
• pathname (or path): The virtual resource path (e.g., /api/users/1).
• headers: A JSON-stringified object containing request headers.

The framework supports a variety of output formats. You can specify the desired format using the produces property in the @RequestMapping decorator (or its aliases like @Get, @Post) or by returning a ResponseEntity with a specific MIME type.

Use this when building Sidebars, Modals, or Add-ons.

Example (Client-side JS):

const path = "/api/users/123";
const method = "GET";
const headers = JSON.stringify({
  "X-Request-Source": "internal"
});

// Constructing the Virtual Transport Event
const event = {
  pathInfo: path,
  parameter: {
    method,
    pathname: path,
    headers
  },
  parameters: {
    method: [method],
    pathname: [path],
    headers: [headers]
  },
  queryString: `method=${method}&pathname=${encodeURIComponent(path)}&headers=${encodeURIComponent(headers)}`
};

google.script.run
  .withSuccessHandler((response) => {
    // Parse the optimized string response
    const result = typeof response === "string" ? JSON.parse(response) : response;

    console.log("Status:", result.status);
    console.log("Data:", result.body);
  })
  .doGet(event);

Use this when accessing the script via a direct link, a webhook, or a third-party service. This returns a standard GAS TextOutput or HtmlOutput.

Example Request URL: https://script.google.com/.../exec?method=GET&pathname=%2Fapi%2Fusers%2F123

The framework automatically handles your controller's return value based on whether the @ResponseBody decorator is used (note that @RestController applies this by default):

If the controller method is not marked with @ResponseBody, the framework returns a full HTTP-like payload:

{
  "status": 200,
  "statusText": "OK",
  "ok": true,
  "headers": { "Content-Type": "application/json" },
  "body": { "id": 123, "name": "John Doe" }
}

If the method is marked with @ResponseBody, the framework bypasses the payload wrapper and returns only the data directly.

Pipes can be used to transform data before it reaches your handler:

The ResponseEntity class provides a flexible way to build full HTTP responses, including status codes, headers, and MIME types.

import { Get, RestController, ResponseEntity, HttpStatus, ContentMimeType, Param } from "bootgs";

@RestController("users")
export class UserController {

    @Get("{id}")
    getUser(@Param("id") id: string): ResponseEntity {
        const user = { id, name: "John Doe" };

        if (!user) {
            return ResponseEntity.status(HttpStatus.NOT_FOUND).build();
        }

        return ResponseEntity.ok()
            .header("X-Custom-Header", "Value")
            .body(user);
    }

    @Get({ path: "export", produces: ContentMimeType.CSV })
    exportData(): ResponseEntity<string> {
        const csvData = "id,name\n1,John Doe";
        return ResponseEntity.ok(csvData);
    }
}

The @ResponseBody decorator indicates that the return value of a method should be bound directly to the response body, bypassing the default framework wrapper (which normally includes status, ok, and body fields in the JSON response).

import { Get, HttpController, ResponseBody } from "bootgs";

@HttpController("raw")
export class RawController {

    @Get("data")
    @ResponseBody()
    getRawData(): object {
        return { message: "This will be returned as the root JSON object" };
    }
}

Transform parameters with pipes:

import {Get, RestController, Query, ParseNumberPipe} from "bootgs";

@RestController("users")
export class UserController {

    @Get("details")
    getUserDetails(@Query("id", ParseNumberPipe) id: number): object {
        return {
            userId: id,
            message: "Success!"
        };
    }
}

Use @ControllerAdvice to handle exceptions globally across the whole application:

import {ControllerAdvice, ExceptionHandler, ResponseStatus} from "bootgs";

@ControllerAdvice()
export class GlobalExceptionHandler {

    @ExceptionHandler(Error)
    @ResponseStatus(500)
    handleError(error: Error): object {
        return {
            status: "Error",
            message: error.message
        };
    }
}

We welcome contributions! Please see our Contributing Guidelines for details on our code of conduct, and the process for submitting pull requests.

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

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

This project is licensed under the Apache-2.0 License.

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