tgas-local

Typescript support for running and testing Google Apps Script (GAS) projects locally.

Why is this necessary?

This project is inspired by the project gas-local, but adds typescript support and modern module syntax. It is frustrating to have to compile your typescript files to javascript after any change in order to run tests on your local apps script files. This package removes that time consuming step, speeding up your development and testing process. Using this package allows you to run and test your apps script files locally in a node environment without needing to make any changes to the files before pushing or pulling your code to the apps script cloud environment using clasp.

Installation

Install this package and the types package for google apps scripts

Via npm

npm i -D tgas-local @types/google-apps-script

Via pnpm

pnpm i -D tgas-local @types/google-apps-script

Optional Plugin

This plugin adds type checking for the return object from gasRequire()

pnpm i -D typescript-plugin-tgas-local

Then add this plugin information to "compilerOptions" in your tsconfig.json file.

{
  // rest of your compilerOptions
  "plugins": [
    {
      "name": "typescript-plugin-tgas-local",
      "apps-script-directory": "./RELATIVE_PATH_TO_YOUR_GAS_FILES"
    }
  ]
}

Usage

// import the gasRequire function
import { gasRequire } from 'tgas-local'

// Pass the relative path from your current working directory to the directory that includes your apps script files.
const gLib = gasRequire('./path-to-local-googleappsscript-directory')

// Call your apps script functions from the gLib object
gLib.yourAppsScriptFunction()

Mocking Google Services

import { type IGlobalMocksObject, gasRequire } from 'tgas-local'

// Create an object that mocks the functions of an Apps Script Service
const mockServices: IGlobalMocksObject = {
  UrlFetchApp: {
    fetch: () => "fetch called!",
    fetchAll: () => "fetchAll called!"
  }
}
// pass it to gasRequire
const gLib = gasRequire('./appsscript-directory', mockServices)

gLib.UrlFetchApp.fetch() // returns the string "fetch called!"

Filtering

Simple file exclusion

// Use the options object to pass a filter function that will filter any unwanted files
// Note: gasRequire is already setup to only read files with the extentions: .ts, .js, .gs
const options = {
  filter: (filePath: string) => {
    return filePath === "some-file-to-not-include.ts"
  }
}
const gLib = gasRequire('./appscript-directory', mockServices, options)

Custom Glob options

// Accepts any valid parameter of the GlobOptions object from the node-glob library.
const options = {
  globOptions: {
    cwd: './some-other-dir',
    absolute: true
    // ...etc
  }
}

Contributing

Pull requests are welcome! I am always open to collaboration.

Inspired by Mikhail Zagorny's gas-local package, but with built in native typescript support.

Built with esbuild and glob

Useful links

• clasp: Develop and manage googleappsscript projects locally
• gas-local: Inspiration for this project
• typescript-plugin-tgas-local: Typescript plugin for strong typing your GAS functions in your tests.