Template for GoogleAppsScript development with TypeScript
Tags: tutorial, typescript, webpack, googleappsscript
Published: 2022-11-06 23:04:41

# 🏰 What is this article about?

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

▶︎▶︎▶︎ <a href="https://github.com/matcher-inc/gas-template" target="_blank" rel="noopener noreferrer">**Template for GoogleAppsScript development with TypeScript**</a> ◀︎◀︎◀︎

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
▶︎▶︎▶︎ <a href="https://github.com/matcher-inc/gas-template" target="_blank" rel="noopener noreferrer">**Template for GoogleAppsScript development with TypeScript**</a> ◀︎◀︎◀︎

### 2. Click [Use thie template] button
<img width="473" src="https://dev-to-uploads.s3.amazonaws.com/uploads/articles/j1an2qq6hb1uvkws9cvg.png">

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

### 3. Clone the repository
```bash
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`

```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:
```bash
$ 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:

```typescript
// 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

<img width="400" src="https://dev-to-uploads.s3.amazonaws.com/uploads/articles/s50gabn2h6t2s43wqyq7.png">

### - 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.

```json:.clasp.json
{
  "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
```bash
# 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`