TypeScript is a typed superset of JavaScript that can compile to plain Apps Script.
Using TypeScript with your clasp
project allows you to use features such as:
- Arrow functions
- Optional structural typing
- Classes
- Type inference
- Interfaces
- And more…
Starting with version 1.5.0
, Clasp allows new and existing Apps Script projects to use TypeScript.
Note: Once you use TypeScript, you cannot develop on script.google.com (the transpiled code).
Warning: Apps Script's runtime/execution is different than Node or web browsers. In particular, you cannot use the terms
export
orrequire
in the same way you would with Node. You cannot usewindow
like in web browsers.
This quickstart guide describes how to create a TypeScript project from scratch.
-
Ensure you have upgraded to clasp's version >= 1.5.0
clasp -v
-
Install TypeScript definitions for Apps Script in your project's folder.
npm i -S @types/google-apps-script
-
Create a file called
tsconfig.json
to enable TypeScript features:
{
"compilerOptions": {
"lib": ["esnext"],
"experimentalDecorators": true
}
}
Create a clasp project in an empty directory (or use an existing project):
clasp create --type standalone
Create a TypeScript file called hello.ts
with the following contents:
const greeter = (person: string) => {
return `Hello, ${person}!`;
}
function testGreeter() {
const user = 'Grant';
Logger.log(greeter(user));
}
Note: This is a valid TypeScript file (but an invalid Apps Script file). That's OK.
Push the TypeScript file to the Apps Script server:
clasp push
Note: clasp automatically transpiles
.ts
files to valid Apps Script files uponclasp push
.
Open the Apps Script project on script.google.com:
clasp open
Notice how a transpiled version of your project was pushed to the Apps Script server.
Run testGreeter()
and press View
> Logs
to view the logs to see the result.
This section lists TypeScript examples derived from this guide:
These features allow you to write Apps Script concisely with intelligent IDE errors and autocompletions.
// Optional Types
let isDone: boolean = false;
let height: number = 6;
let bob: string = "bob";
let list1: number[] = [1, 2, 3];
let list2: Array<number> = [1, 2, 3];
enum Color {Red, Green, Blue};
let c: Color = Color.Green;
let notSure: any = 4;
notSure = "maybe a string instead";
notSure = false; // okay, definitely a boolean
function showMessage(data: string): void { // Void
console.log(data);
}
showMessage('hello');
// Classes
class Hamburger {
constructor() {
// This is the constructor.
}
listToppings() {
// This is a method.
}
}
// Template strings
var name = 'Sam';
var age = 42;
console.log(`hello my name is ${name}, and I am ${age} years old`);
// Rest arguments
const buildName = (first: string, ...rest) => first + ' ' + rest.join(' ');
buildName('First', 'Second', 'Third');
// Spread operator (array)
let cde = ['c', 'd', 'e'];
let scale = ['a', 'b', ...cde, 'f', 'g']; // ['a', 'b', 'c', 'd', 'e', 'f', 'g']
// Spread operator (map)
let mapABC = { a: 5, b: 6, c: 3};
let mapABCD = { ...mapABC, d: 7}; // { a: 5, b: 6, c: 3, d: 7 }
// Destructure map
let jane = { firstName: 'Jane', lastName: 'Doe'};
let john = { firstName: 'John', lastName: 'Doe', middleName: 'Smith' }
function sayName({firstName, lastName, middleName = 'N/A'}) {
console.log(`Hello ${firstName} ${middleName} ${lastName}`)
}
sayName(jane) // -> Hello Jane N/A Doe
sayName(john) // -> Helo John Smith Doe
// Export (The export keyword is ignored)
export const pi = 3.141592;
// Google Apps Script Services
var doc = DocumentApp.create('Hello, world!');
doc.getBody().appendParagraph('This document was created by Google Apps Script.');
// Decorators
function Override(label: string) {
return function (target: any, key: string) {
Object.defineProperty(target, key, {
configurable: false,
get: () => label
});
}
}
class Test {
@Override('test') // invokes Override, which returns the decorator
name: string = 'pat';
}
let t = new Test();
console.log(t.name); // 'test'
After installing @types/google-apps-script
, editors like Visual Studio Code autocomplete types:
var doc = DocumentApp.create('Hello, world!');
doc.getBody().appendParagraph('This document was created by Google Apps Script.');
Logger.log(doc.getUrl());
In this case, we could write the fully qualified type:
const doc: GoogleAppsScript.Document.Document = DocumentApp.create('Hello, world!');
Or inferred type:
const doc = DocumentApp.create('Hello, world!');
In most cases, the inferred type is sufficient for Apps Script autocompletion.
clasp push
transpiles ES6+ into ES3 (using ts2gas
) before pushing files to the Apps Script server.
Enabling advanced services modifies the appsscript.json
file on script.google.com. After enabling an advanced service in the UI, copy the appsscript.json
file from script.google.com into your editor to use the advanced services in your project.
Advanced Service should have TypeScript autocompletion.
Currently, clasp
supports [email protected]
. If there is a feature in a newer TypeScript version that you'd like to support, or some experimental flag you'd like enabled, please open an issue.
- You can create a TypeScript configuration file by creating a
tsconfig.json
file in the same folder as your.clasp.json
file. - Only the
"compilerOptions"
section is considered. Anything else is ignored.
By default "compilerOptions"
uses these options:
{
"isolatedModules": true,
"noLib": true,
"noResolve": true,
"target": "ES3",
"module": "None",
"noImplicitUseStrict": true,
"experimentalDecorators": true,
}
Note that the options
isolatedModules
,noLib
,noResolve
andmodule
cannot be changed.
If your Apps Script project is configured to use the V8 Engine, you should set "target": "ES2019"
in your tsconfig.json
.
Currently, Google Apps Script does not support ES modules. Hence the typical export
/import
pattern cannot be used and the example below will fail:
// module.ts
// `foo` is added to the `exports` object in the global namespace
export const foo = 'Hello from Module';
// main.ts
import { foo } from './module'; // this statement is ignored
// the variable `foo` does not exist in the global namespace
const bar = foo;
There are some possible workaround though:
This workaround makes TypeScript aware of the exports
object and its "imported" content. Please be aware that this approach does not even remotely offer proper code isolation one would assume from using modules and can cause issues that will be very hard to debug.
declare const exports: typeof import('./module');
exports.foo; // address "imported" content as it will be visible when transpiled
This workaround takes advantage of TypeScript "namespaces" (formerly known as "internal module") and achieves proper code isolation.
Namespace definition can be nested, spread over multiple files and do not need any import
/require
statement to be used.
// module.ts
namespace Module {
export function foo() {}
function bar() {} // this function can only be addressed from within the `Module` namespace
}
// anyFiles.ts
Module.foo(); // address a namespace's exported content directly
const nameIWantForMyImports = Module.foo; // to simulate `import` with renaming
nameIWantForMyImports();
For a more detailed example on how namespace
s can be used in a project you can visit ts-gas-project-starter
Here the idea is to use third party tools (webpack, rollup.js, gulp, etc.) to do the following:
- parse your code and indentify module used (
export
andimport
) - (optional) do some tree shaking in order to remove unused code
- pack the result into a single javascript package
At one of the steps above, transpilling TypeScript into JavaScript must occur (either by using TypeScript or Babel) but which precise step will be defined by the set of third party tools you choose and how you define your build chain.
For an example on how this could be set up using rollup.js, see esmodules.md.
Documenting in detail any solution with third party tools is currently beyond the scope of this document. If you happen to setup such a build chain and want to share it with the community, please open an issue so that it can be reviewed and evaluated for completing the documentation.
If your project contains libraries referenced in appsscript.json
, TypeScript will throw errors for the library names or types it cannot resolve, e.g. [ts] Cannot find name 'OAuth2'. [2304]
. Libraries have their own types and are not part of @types/google-apps-script
. These libraries are only resolved once the script is deployed upstream with clasp push
.
If the @types npm package exists for a GAS library, you can install it as so:
npm install -D @types/google-apps-script-oauth2
Add the types reference to your tsconfig.json
file:
{
"compilerOptions": {
"types": ["google-apps-script", "google-apps-script-oauth2"],
"strict": true
}
}
Not all libraries will have type definitions, so you may have to create your own. Refer to the Outdated Types section below for more details.
If you do not want to generate types, a lazier workaround for this error is to ignore the line causing the TypeScript error by adding a line comment // @ts-ignore
above the line. This can be done as so:
function getOAuthService() {
// Ignore OAuth2 library resolution when working locally with clasp and TypeScript
// @ts-ignore
return OAuth2.createService('Auth0');
}
TypeScript types for Apps Script are currently generated manually.
If you see outdated TypeScript types, you can help update them by contributing to @types/google-apps-script.
- Fork DefinitelyTyped/DefinitelyTyped
- Run the types generator by following the instructions at motemen/dts-google-apps-script
- Copy the type files to your fork of
DefinitelyTyped/DefinitelyTyped
. - View the diff (
git diff
), and make sure that the types look OK. - Make a PR and ask @grant for review.
- Consider using a linter like
gts
to increase the quality of your TypeScript projects.