Type definitions and utilities for Google Apps Script client-side API
npm install @ciderjs/gasnuki
Type definitions and utilities for Google Apps Script client-side API
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.
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.
``bash`
npm install @ciderjs/gasnuki
or
`bash`
pnpm add @ciderjs/gasnuki
1. Generate type definitions by running:
`bash`
npx @ciderjs/gasnuki
... or, add project's npm-script in package.json:
`jsonc`
{
// others...
"scripts": {
"gas": "gasnuki"
}
}
This will generate type definition files in the types directory by default.
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:
`bash`
pnpm add -D vite @ciderjs/gasnuki
2. Add the plugin to your vite.config.ts:
`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:
`jsonc`
{
"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.
`ts
// Type-safe access to google.script.run
// Example: Call the server-side function getContent
google.script.run
.withSuccessHandler((result) => {
console.log(result);
})
.getContent('Sheet1');
`
gasnuki provides the following features to deliver a superior developer experience.
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.
@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.
`ts:lib/gas.ts
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
`
2. Use the created gas object to call your server-side functions with async/await.
`ts:components/MyComponent.tsx
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);
}
}
`
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.
`ts:lib/gas.ts
import {
getPromisedServerScripts,
type PartialScriptType,
} from '@ciderjs/gasnuki/promise';
import type { ServerScripts } from '../types/appsscript';
// Define mockup functions for development
const mockupFunctions: PartialScriptType
// 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
`
Normally, using JSON.parse() for communication between Google Apps Script and the client results in an any return type. Additionally, types like Date are converted to strings during serialization and require manual restoration.
gasnuki preserves the original type information as a Branded Type (JsonString), enabling type-safe restoration without using any.
By passing { parseJson: true } as the second argument to getPromisedServerScripts, it will automatically deserialize return values that were serialize()-ed on the server side, including proper Date object recovery.
`ts
// Server-side (Apps Script)
// const getAppData = () => serialize({ updatedAt: new Date(), user: 'Alice' });
// Client-side
export const gas = getPromisedServerScripts
parseJson: true
});
async function fetchData() {
// The return value is inferred as the original object type instead of any
// Date objects are also automatically recovered
const result = await gas.getAppData();
console.log(result.user); // 'Alice' (string)
console.log(result.updatedAt instanceof Date); // true
}
Bug reports and pull requests are welcome. Please use the issues or pull requests` section.
MIT