Template for GoogleAppsScript development with TypeScript

Ryo-Nakano — Sun, 06 Nov 2022 23:04:41 +0000

🏰 What is this article about?

In this article, you will learn how to develop GoogleAppsScript projects in local with TypeScript by my template.

▶︎▶︎▶︎ Template for GoogleAppsScript development with TypeScript ◀︎◀︎◀︎

This is a MINIMUM template to keep the contents easily understandable for beginners, so anyone can easily start developing using my template.

Clasp
Webpack
TypeScript

These three are main components of this template.

👨 Who am I?

I am a Japanese software engineer at Matcher Inc. in Japan, and have been an engineer for two years. I have written articles in Japanese before, but this is my first time to write articles in English, so it is a challenge for me.

There may be parts of the English that are difficult to understand or incorrect. I would be happy if you could point them out to me.

🙋‍♀️ Who is it for?

People who have experience developing in GoogleAppsScript, such as those who meet the following criteria:

Who want to use git
Who want to use your favorite editor (e.g. VSCode)
Who want to develop in directories divided by function
Who want to use npm modules
Who want to use develop with TypeScript
Who want to upgrade your development experience

If you are new to GoogleAppScript development, this template may be difficult to use. In that case, I recommend that you try it once you have some experience in GoogleAppsScript development.

🏃‍♂️ Get started

0. Set the conditions

To proceed to the next step, must have the following ready:

Create empty GoogleAppsScript project
- https://script.google.com/home/start
Enable GoogleAppsScript API
- https://script.google.com/home/usersettings

Tested environment 1: Ubuntu

Ubuntu: 18.04.6 LTS
node: v16.16.0
npm: 8.18.0
clasp: 2.4.1
webpack: 5.74.0
webpack-cli: 4.10.0
TypeScript: 4.8.3

Tested environment 2: Mac

MacOS: 11.6
node: v16.17.1
npm: 8.15.0
clasp: 2.4.1
webpack: 5.74.0
webpack-cli: 4.10.0
TypeScript: 4.8.3

1. Visit github template

▶︎▶︎▶︎ Template for GoogleAppsScript development with TypeScript ◀︎◀︎◀︎

2. Click [Use thie template] button

※ You have to logged in to github to get the button

3. Clone the repository

git clone <Your template url> my-gas-project

 or

# If you don't want to use as template
git clone https://github.com/matcher-inc/gas-template.git my-gas-project

4. Move directory

cd my-gas-project

5. Install npm dependencies

npm install

6. Past your Script ID in the `.clasp.json`

{
  "scriptId": "<Your Script ID>",
  "rootDir": "./dist/"
}

7. If you are new to clasp, run the following command and authorize clasp

npx clasp login --no-localhost

8. Execute `npm run deploy`

If npm run deploy execution is successful, you will see something like this:

$ npm run deploy

> gas-template@1.0.0 deploy
> webpack && clasp push

asset bundle.js 3.87 KiB [emitted] (name: main)
runtime modules 891 bytes 4 modules
cacheable modules 234 bytes
  ./src/index.ts 170 bytes [built] [code generated]
  ./src/sample_module/index.ts 64 bytes [built] [code generated]
webpack 5.74.0 compiled successfully in 1853 ms
└─ dist/appsscript.json
└─ dist/bundle.js
Pushed 2 files.

Checkpoints if it doesn't work:

🚨 Required modules installed with npm install?
If the node_modules folder is empty, npm install has not been executed successfully.

🚨 Script ID correctly pasted into .clasp.json?
If the correct Script ID is not pasted, Clasp can't reflect the latest developments.

🚨 Clasp authorization is succeeded?
If Clasp is not authenticated, Clasp can"t reflect the latest developments.

🚨 Running npm run deploy in the correct directory?
If you have followed the steps described in the article, make sure you have run npm run deploy in the my-gas-project directory.

❗️ Usage notes

- Declare functions as a property of the global object at src/index.tsf

Functions must be declared as a property of the global object as follows:

// at src/index.ts

// import functions declared in other files
import { sampleFunc } from 'sample_module';

// embed an imported function in the global object
(global as any).func1 = sampleFunc;

// embed an arrow function in the global object
(global as any).func2 = (): void => {
  const msg: string = 'hello hello !!';
  console.log(msg);
};

Declaring functions in this way allows functions to be selected and executed in web editor.

- Clasp overwrites your codes on push

What Clasp can do is OVERRRIDE.

Clasp cannot detect differences and reflect them, so I do not recommend using this template for projects under development.

📚 Brief description of the project files

- dist

Webpack bundles all the files in the src folder into a single file, bundle.js. The completed file bundle.js is placed in the dist folder.

appscript.json is a kind of configuration file of GoogleAppsScript projects. There is basically no need to modify this file.

- node_modules

node_modules is a folder that has modules installed by npm install. What to install with npm install is described in package.json, so node_modules folder is excluded from management by git. (Configured in .gitignore)

- src

src is a main folder used for development. src/index.ts is a starting point for bundling files by Webpack. Please make sure to create src/index.ts. (Configured in webpack.config.js)

- .clasp.json

.clasp.json is a configuration file for Clasp.

{
  "scriptId": "<Your Script ID>",
  "rootDir": "./dist/"
}

Paste your Script ID into the <Your Script ID> field.

- .gitignore

.gitignore is a file that is used to specify what you don't want git to manage. In this template, the following three items are specified as unmanaged.

node_modules
dist/bundle.js
.clasp.json

- package.json

package.json is a list of packages you want installed when you npm install.

package-lock.json and package.json are not similar.

To explain very roughly
・package.json → shopping "to do" list
・package-lock.json → shopping "done" list
and so on.

- README.md

Just a description.

- tsconfig.json

tsconfig.json is a configuration file for TypeScript. There is basically no need to modify this file.

- webpack.config.js

webpack.config.js is a configuration file for Webpack. There is basically no need to modify this file.

🚀 Commands

# webpack build
npm run build

# webpack build in watch mode
npm run build:watch

# push dist files to script.google.com
npm run push

# push dist files to script.google.com in watch mode
npm run push:watch

# webpack build & push dist files to script.google.com
npm run deploy

The following two commands will make development easier:
・npm run build:watch
・npm run push:watch

Forem: Ryo-Nakano