🏰 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:

1. Create empty GoogleAppsScript project
   • https://script.google.com/home/start
2. 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