DEV Community

Cover image for I created a Boiler Plate for creating Web Apps with Google Apps Script.
Mikoshiba Kyu
Mikoshiba Kyu

Posted on

I created a Boiler Plate for creating Web Apps with Google Apps Script.

GAS-WebApp-BoilerPlate

Boilerplate for creating web apps with Google Apps Script.

We expect to develop in TypeScript and React.

GitHub logo Mikoshiba-Kyu / gas-webapp-boilerplate

Template for creating web apps with Google Apps Script

License Downloads Size

clasp Vite TypeScript React Vitest Playwright Github Actions

GAS-WebApp-BoilerPlate

English / ζ—₯本θͺž

Boilerplate for creating web apps with Google Apps Script.
We expect to develop in TypeScript and React.

Feature

  • DevContainer is used
  • Vite and clasp generate files for eventual deployment in Google Apps Script
  • Unit tests can be created with Vitest and E2E tests with Playwright

Quick Start

git clone https://github.com/Mikoshiba-Kyu/gas-webapp-boilerplate.git

Overview of Project Structure

The core development code is placed under the src folder for the front end and back end, respectively.

πŸ“ src
β”œβ”€β”€ πŸ“ backend
β”‚   β”œβ”€β”€ πŸ“ serverFunctions
β”‚   β”‚   β”œβ”€β”€ πŸ“„ index.ts
β”‚   β”‚   └── πŸ“„ and more...
β”‚   └── πŸ“„ main.ts
└── πŸ“ frontend
    β”œβ”€β”€ πŸ“„ main.tsx
    └── πŸ“„ and more...

The yarn build creates files for Google Apps Script in the gas/dist folder.

πŸ“ gas
β”œβ”€β”€ πŸ“ dist
β”‚   β”œβ”€β”€ πŸ“„ index.html
β”‚   └── πŸ“„ main.js
└── πŸ“„ appsscript.json

Other folders are described below.

  • .github Preset Github Actions for E2E…

Feature

  • DevContainer is used
  • Vite and clasp generate files for eventual deployment in Google Apps Script
  • Unit tests can be created with Vitest and E2E tests with Playwright

Quick Start

git clone https://github.com/Mikoshiba-Kyu/gas-webapp-boilerplate.git
Enter fullscreen mode Exit fullscreen mode

Overview of Project Structure

The core development code is placed under the src folder for the front end and back end, respectively.

πŸ“ src
β”œβ”€β”€ πŸ“ backend
β”‚   β”œβ”€β”€ πŸ“ serverFunctions
β”‚   β”‚   β”œβ”€β”€ πŸ“„ index.ts
β”‚   β”‚   └── πŸ“„ and more...
β”‚   └── πŸ“„ main.ts
└── πŸ“ frontend
    β”œβ”€β”€ πŸ“„ main.tsx
    └── πŸ“„ and more...
Enter fullscreen mode Exit fullscreen mode

The yarn build creates files for Google Apps Script in the gas/dist folder.

πŸ“ gas
β”œβ”€β”€ πŸ“ dist
β”‚   β”œβ”€β”€ πŸ“„ index.html
β”‚   └── πŸ“„ main.js
└── πŸ“„ appsscript.json
Enter fullscreen mode Exit fullscreen mode

Other folders are described below.

  • .github Preset Github Actions for E2E test execution.
  • .husky Preset lint at pre commit time.
  • e2e Stores Playwright test files.

Development

Launch DecContainer

Clone the repository and start DevContainer in any way you wish.

Front-end implementation

Implement the front-end side in src/frontend.

Common UI frameworks, state management libraries, etc. can be used.

Back-end implementation

Google Apps specific classes such as SpreadsheetApp cannot be used directly from the front end.

You must call the function exposed to global in backend/main.ts via gas-client from the front end.

// backend/main.ts

import { sampleFunction } from './serverFunctions'

declare const global: {
  [x: string]: unknown
}

// This function is required to run as a webApp
global.doGet = (): GoogleAppsScript.HTML.HtmlOutput => {
  return HtmlService.createHtmlOutputFromFile('dist/index.html')
}

// Create the necessary functions below.
global.sampleFunction = sampleFunction
Enter fullscreen mode Exit fullscreen mode
// frontend/App.tsx

import { GASClient } from 'gas-client'
const { serverFunctions } = new GASClient()

...
...

const handleButton = async () => {
    if (import.meta.env.PROD) {
        try {
        const response: number = await serverFunctions.sampleFunction(count)
        setCount(response)
        } catch (err) {
        console.log(err)
        }
    } else {
        setCount(count + 1)
    }
}

...
...
Enter fullscreen mode Exit fullscreen mode

πŸ—’οΈNotes

In the above example, import.meta.env.PROD is used to branch by environment.

If created by yarn build and deployed in GAS, the environment uses serverFunction,
And if it is running locally by yarn dev, it will work in an alternative way.

Creating and running tests

Unit testing

$ yarn test:unit
Enter fullscreen mode Exit fullscreen mode

For front-end and unit testing, use Vitest.

If you want to test Google Apps specific functions created in serverFunctions, you need to mock them.

E2E testing

$ yarn test:e2e
Enter fullscreen mode Exit fullscreen mode

Playwright is used for E2E testing.

The URL of an already running GAS web app must be specified as baseURL.

// playwright.config.ts

...
...

use: {
    /* Base URL to use in actions like `await page.goto('/')`. */
    baseURL: process.env.PLAYWRIGHT_BASE_URL || 'your apps url',
  },

...
...
Enter fullscreen mode Exit fullscreen mode

⚠️ Important
When conducting E2E testing, the target application must be made available to everyone.


Deployment

First, compile with Vite.

$ yarn build
Enter fullscreen mode Exit fullscreen mode

If you are not logged in to clasp, log in.

$ clasp login
Enter fullscreen mode Exit fullscreen mode

Create a new project if one has not already been created.

When you create a project as follows, a new file appsscript.json will be created in the root.

If you want to use the one already placed in the gas folder, you can delete it.

$ clasp create

? Create which script?
  standalone
  docs
  sheets
  slides
  forms
> webapp
  api
Enter fullscreen mode Exit fullscreen mode

πŸ—’οΈNotes

If you are using a project that has already been created,

manually create .clasp.json in the root and specify the scriptId directly.

πŸ—’οΈNotes

Set "timeZone" in gas/appscript.json according to your situation.

Replace the rootDir in the created .clasp.json with the path to the gas folder of the project.

{
  "scriptId": "********",
  "rootDir": "/workspaces/gas-webapp-boilerplate/gas"
}
Enter fullscreen mode Exit fullscreen mode

Execute deployment.

$ clasp push
$ clasp deploy
Enter fullscreen mode Exit fullscreen mode

To open the deployed project page in a browser, use the following command.

$ clasp open
Enter fullscreen mode Exit fullscreen mode

Top comments (0)