Development Setup

This guide covers setting up your development environment for efficient add-on development with hot module replacement and live preview inside Google Workspace.

Local Development

Start the development server with port forwarding up and running (see below).

cd addon
yarn run start:sheets # For Sheets only

or for all enabled workspace types:

cd addon
yarn run start # For all enabled types

This starts a Vite dev server with HMR for previewing your UI outside of Google Workspace.

Live Development Inside Google Workspace

The most powerful development feature is the ability to develop your React client locally while seeing changes instantly inside the actual Google add-on window—no redeployment needed.

How It Works

In development mode, the add-on loads a wrapper HTML that embeds an iframe pointing to your local Vite dev server. The gas-client library bridges communication between your local React app and the Apps Script server functions.

┌─────────────────────────────────────────────────────────┐
│  Google Sheets/Docs/Slides/Forms                        │
│  ┌───────────────────────────────────────────────────┐  │
│  │  Sidebar (wrapper HTML pushed to Apps Script)     │  │
│  │  ┌─────────────────────────────────────────────┐  │  │
│  │  │  iframe → Your Local Dev Server (via tunnel)│  │  │
│  │  │  - Hot Module Replacement (HMR)             │  │  │
│  │  │  - Instant React updates                    │  │  │
│  │  │  - Full Vite dev experience                 │  │  │
│  │  └─────────────────────────────────────────────┘  │  │
│  └───────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────┘

1. Create an HTTPS Tunnel

Google's iframe requires HTTPS. Create a tunnel to expose your local dev server:

Option A: VS Code Ports (recommended)

1. Open the Ports panel in VS Code (Cmd+Shift+P > "Ports: Focus on Ports View")
2. Forward port 3000
3. Set visibility to Public
4. Copy the tunnel URL (e.g., https://xxxxxxxx-3000.brs.devtunnels.ms)

Option B: ngrok

ngrok http 3000

Copy the HTTPS URL from the output.

2. Configure the Tunnel URL

Update addon/src/constants.ts with your tunnel URL:

// constants.ts
export const DEV_SERVER_URL = "https://your-tunnel-url";

3. Start Live Development

cd addon
yarn run start:sheets

This command:

1. Builds the server code and wrapper HTML with your tunnel URL
2. Pushes the wrapper to Apps Script
3. Starts the local Vite dev server

4. Develop with Instant Feedback

1. Open your Google document and launch the add-on sidebar
2. The sidebar loads your local React app via the tunnel
3. Edit your React components—changes appear instantly via HMR
4. Server function calls still work (routed through gas-client)

Tips

• Keep the tunnel stable: VS Code Ports tunnels persist across restarts
• One app at a time: Use yarn start:sheets instead of yarn start for faster iteration on a specific app type
• Server changes still require deploy: Only client React code hot-reloads; server function changes need yarn deploy

Build Commands

Building for Production

yarn build

Output is written to addon/dist/:

• sidebar.html - Inlined sidebar app
• dialog.html - Inlined dialog app
• code.js - Bundled server code

Deploying

yarn deploy

Pushes the dist folder to Google Apps Script using clasp.

Utility Scripts

The boilerplate includes several helper scripts in addon/scripts/:

Running Scripts

# Open all test documents
./scripts/open-all.sh

# Open only Sheets test document
./scripts/open-type.sh sheets

# Push to all projects
./scripts/push-all.sh

# Push to Sheets project only
./scripts/push-type.sh sheets