@dgcode/gscript

Code and test in Node, deploy to Google Apps Script

DISCLAIMER

This is a highly experimental tool! Use at your own risk. If you want a more official and battle-tested solution (with the caveats listed below), use clasp instead, keeping in mind both tools achieve very different purposes.

In its current state, consider this a "beta" project with few documentation and rough edge-cases - for the time being.

Install

$ npm install @dgcode/gscript

To get the command-line gscript tool instead, install the package globally:

$ npm install @dgcode/gscript -g

Usage

From scratch

Print help, command usage and options:

$ gscript help

Create a new project (follow prompt instructions):

$ gscript create

If you'd rather generate a YAML configuration file instead for your project (which conveniently includes some documentation for customization):

$ gscript create --format yaml

Code then deploy to Google Apps Script:

$ gscript push

Editing

Clone an existing Google Apps Script project (this will retrieve code and write files locally):

$ gscript clone

Save current Apps Script code as new locked version:

$ gscript bump

Retrieve current Apps Script code (in case local files are missing):

$ gscript pull

Compile files locally to check what will eventually be pushed, based on your source files:

$ gscript compile

Workflow

Open current Apps Script UI to view final deployed code:

$ gscript open

Run a local development server to preview your view files (React):

$ gscript dev --port YOUR_PORT

gscript vs Google's clasp

gscript is a more opinionated tool about how a project should be designed and coded, while clasp provides a thinner layer that merely keeps local and remote files synchronized.

Building

clasp maintains a one-to-one relationship between your local files and files in the Apps Script project, while gscript bundles your files into a single compiled one with help of Webpack.

Being powered by Webpack enables gscript to compile into environment-agnostic code - notably one that understands import {...} from '' / require('') calls and includes all dependencies in a single wrapped Apps Script file without polluting the global namespace.

For example, if your local TypeScript code was made of:

// local file: main.ts

import { FooLogger } from './foo-logger';

export function sayHello() {
  const logger = new FooLogger();
  logger.print();
}

// local file: foo-logger.ts

export class FooLogger {
  public print() {
    console.log('Hello from Foo!');
  }
}

Then these will eventually be transformed and packed into a single file when sent to the Apps Script project, looking like:

// compiled Apps Script file: Entry.gs

function sayHello() {
  return entry.sayHello.apply(entry, arguments);
}

!(function webpackCompilation(global) {
  global['entry'] = (function() {
    // webpack-compiled magic goes here
    // ...
  })();
})(this);

Local-first, transform later

gscript is designed with local-first code in mind, letting you benefit from any IDE features you like (auto-completion, type checking) such as VSCode's. Moreover, gscript applies arbitrary code transforms that let you run your script locally first before publishing to Apps Script. For example:

// in the local world:
console.log('Hello, %s!', 'Joe');

... is compatible in classic JavaScript (both Node.js and browsers) but is unknown from Apps Script, which uses its own global Logger class instead. On compilation, gscript automatically transforms such code as:

// same code, automatically transformed by gscript
// once published on Apps Script:
Logger.log('Hello, %s!', 'Joe');

Entry points

Being compiled with Webpack, you code needs to specify known entry files.

By default, any file starting with main- or Main will be considered an entry point. Such file should explicitly expose functions, in the following form:

export function someFunction() {...}

This will ensure AppsScript recognizes such function at top-level callables.

Roadmap

TODO more documentation to come in future versions

License

MIT