@ciderjs/gasnuki

Type definitions and utilities for Google Apps Script client-side API

Overview

gasnuki automatically extracts type definitions from your server-side Google Apps Script functions, providing a fully type-safe google.script.run API for your client-side code. This bridges the gap between your Apps Script backend and modern frontend development with autocompletion and robust type-checking.

The developer experience gasnuki Delivers

gasnuki dramatically improves the often-frustrating developer experience of building web applications with Google Apps Script.

• Full Type Safety: Say goodbye to guesswork. With typed arguments and return values for google.script.run, you get full autocompletion and compile-time checks in your editor.
• Modern Async Syntax: Write clean, intuitive code using async/await for your server-side calls, freeing you from callback hell.
• Rapid Development Cycles: No more waiting for clasp push every time you want to test a frontend change. The mocking feature allows you to develop your UI swiftly and offline.
• Seamless Integration: With the Vite plugin, your client-side types are automatically regenerated whenever you save a change in your server-side code, creating a truly seamless workflow.

Installation

npm install @ciderjs/gasnuki

or

pnpm add @ciderjs/gasnuki

Usage

1. Generate type definitions by running:

npx @ciderjs/gasnuki

... or, add project's npm-script in package.json:

{
  // others...
  "scripts": {
    "gas": "gasnuki"
  }
}

This will generate type definition files in the types directory by default.

Vite Plugin Usage

If you are using Vite, you can integrate gasnuki as a plugin to automatically generate types when your server-side files change.

1. Install vite and @ciderjs/gasnuki:

   pnpm add -D vite @ciderjs/gasnuki

2. Add the plugin to your vite.config.ts:

   import { defineConfig } from 'vite';
   import { gasnuki } from '@ciderjs/gasnuki/vite';
   
   export default defineConfig({
     plugins: [
       gasnuki({
         /* options */
       }),
     ],
   });

   Now, when you run vite dev, gasnuki will automatically watch for changes in your Apps Script source files and regenerate the types.

2. Make sure the generated directory (default: types) is included in your tsconfig.json:

{
  "compilerOptions": {
    // ... your options ...
  },
  "include": [
    "src",
    "types" // Add this line if your type definitions are in the 'types' directory
  ]
}

3. Then, you can use google with Type Definitions.

// Type-safe access to google.script.run
// Example: Call the server-side function getContent

google.script.run
  .withSuccessHandler((result) => {
    console.log(result);
  })
  .getContent('Sheet1');

Core Features

gasnuki provides the following features to deliver a superior developer experience.

Automatic Type Generation for Server Functions

Running the gasnuki command parses the .ts files in your Apps Script project, extracts the signatures of all your published server-side functions, and generates a type definition file. This file makes your functions safely callable from the client-side google.script.run.

Modern, Promise-Based API Wrapper

@ciderjs/gasnuki/promise transforms the traditional callback-based API into a type-safe, Promise-based wrapper that supports async/await.

1. Import the getPromisedServerScripts function and pass it the ServerScripts type generated by gasnuki.

   import { getPromisedServerScripts } from '@ciderjs/gasnuki/promise';
   // Specify the path to the type definitions generated by gasnuki
   import type { ServerScripts } from '../types/appsscript';
   
   export const gas = getPromisedServerScripts<ServerScripts>();

2. Use the created gas object to call your server-side functions with async/await.

   import { gas } from '../lib/gas';
   
   async function fetchData() {
     try {
       // The arguments and return value of 'getContent' are now type-safe!
       const result = await gas.getContent('Sheet1');
       console.log(result);
     } catch (error) {
       console.error(error);
     }
   }

Mocking for Accelerated Frontend Development

By passing a mock object to getPromisedServerScripts, you can develop your frontend without needing to clasp push. This allows for rapid testing and debugging of your UI without any dependency on the live backend logic.

import {
  getPromisedServerScripts,
  type PartialScriptType,
} from '@ciderjs/gasnuki/promise';
import type { ServerScripts } from '../types/appsscript';

// Define mockup functions for development
const mockup: PartialScriptType<ServerScripts> = {
  // Simulate the behavior of the sayHello function
  sayHello: async (name) => {
    await new Promise(resolve => setTimeout(resolve, 500)); // Simulate network delay
    return `Hello from mockup, ${name}!`;
  },
  // Other functions can be mocked similarly
};

export const gas = getPromisedServerScripts<ServerScripts>(mockup);

Contributing

Bug reports and pull requests are welcome. Please use the issues or pull requests section.

License

MIT