Local dev environment setup for Google Apps Script using Typescript

README.md

Setting up your local development environment for writing Google Apps Script projects using Typescript

Google Apps Script (GAS) is a superset of ES5, but does NOT include any ES6 features. Also, the browser-based GAS editor is not the best. To make GAS development less miserable, develop locally (i.e. not in the browser) using TypeScript instead!

Google's clasp tool will transpile your code from Typescript to GAS and upload to your GAS project where you can run it.

1. Intall stuff!
   • Visual Studio Code
   • npm
   • TypeScript: npm install -g typescript
   • clasp: npm install -g @google/clasp
     • Be sure to follow instructions for enabling the Apps Script API!
   • ESLint: npm install -g eslint
   • TSLint: npm install -g tslint
2. Create projects
   • Create your GitHub repo
   • Create a new Google Apps Script (GAS) project and save to a Team Drive
   • From the GAS editor go to File > Project Properties and grab the Script ID
3. Local setup
   • Clone GitHub repo
   • From terminal, navigate to repo directory and run clasp clone <Script ID>
   • Run npm init (OK to use all default settings - keep hitting enter)
   • Run eslint --init (recommendation: use the Google style guide in json format) (also might need to use sudo for this and some of the following commands)
   • Run tslint --init
   • Install type definitions for Apps Script in the project directory: npm install --save @types/google-apps-script
   • Create a file named jsconfig.json with the following contents:

     {
         "compilerOptions": {
             "lib": ["esnext"]
         }
     }

   • Create a file named tsconfig.json with the following contents:

     {
         "compilerOptions": {
             "allowJs": true,
             "checkJs": true,
             "types": ["@types/google-apps-script"],
             "strictNullChecks": true
         }
     } 

   • Recommended: disable some of the annoying tslint rules. Open tslint.json and update the "rules" object to be:

     "rules": {
         "eofline": false,
         "interface-name": false,
         "object-literal-sort-keys": false,
         "no-consecutive-blank-lines": false
     },

   • Create a file named .claspignore with the following contents to avoid pushing unneccesary files to the GAS project (note: it's a little tricky to get clasp to ignore node_modules/):

     node_modules/*
     node_modules/**
     node_modules/**/.*
     node_modules/**/.*/**
     
     .eslintrc.js

4. Build stuff!
   • Simply rename any .gs files to .ts and then go nuts with the TypeScript
     • e.g rename Code.gs to Code.ts
     • Note: default parameter values apparently do NOT work after transpilation to GAS, so avoid them
   • OK to move .ts files to subdirectories; will still work just fine after transpilation/upload to GAS editor
   • Use normal git/GitHub process
   • Run clasp push, which does two things:
     • Transpiles your ts code to gs (GAS code)
     • Uploads your code to the GAS project
   • If there are any errors in your ts code, the clasp push may look like it was successful, but actually fail. Look at the generated gs code to be sure it was successful. You can force push with clasp push -f if need be.
   • Run clasp open to open the GAS editor in your browser. From there you can finally execute your code.
   • Also from the GAS editor you can set up triggers as needed to automatically run your script periodically