他の導入ガイド(全7件)
GAS / 導入ガイド
@ciderjs/gasnuki
Google Apps Scriptとフロントエンドを自動推論する型でつなぐ
npm install --save @ciderjs/gasnukiこのページの内容
@ciderjs/gasnuki は、Google Apps Script (GAS) のサーバーサイド TypeScript コードから型定義を自動抽出し、クライアントサイドの google.script.run API に対する型定義および Promise ベースのユーティリティを提供するライブラリです。
概要と特徴
Google Apps Script の HtmlService を用いた Web アプリケーション開発では、クライアントから呼び出すサーバー関数の引数・戻り値に型定義が存在せず、withSuccessHandler / withFailureHandler によるコールバック記述やローカル開発時のモック構築、Date オブジェクトのシリアライズ欠落といった課題が生じます。@ciderjs/gasnuki は静的解析と軽量なランタイムユーティリティによってこれらを一括解決します。
- 静的解析 (
ts-morph) による型定義の自動抽出: サーバーサイドの.tsコードを解析し、公開関数のシグネチャ・JSDoc・関連インターフェースを抽出した型定義ファイル(types/appsscript.ts)を自動生成します。 google.script.runの Promise ラッパーとローカルモック:ProxyベースのgetPromisedServerScriptsにより、サーバー関数をasync / awaitで呼び出せるほか、vite dev等のローカル環境では自動的にモック関数へフォールバックします。- 型情報を維持する JSON シリアライズ (
JsonString<T>): Branded Type を用いたserialize/deserializeとparseJson: trueオプションにより、Dateインスタンスを含むオブジェクトも型安全性と実体を保ったまま送受信できます。 - Vite 開発サーバーとのシームレスな統合:
@ciderjs/gasnuki/viteプラグインにより、サーバーコードの編集を検知してリアルタイムに型定義を再生成します。
動作要件
- Node.js:
>= 20.x推奨 - TypeScript:
>= 5.x - Vite:
^7 || ^8(Vite プラグイン@ciderjs/gasnuki/viteを使用する場合)
インストール
パッケージマネージャーを使用してインストールします。クライアントサイドで @ciderjs/gasnuki/promise や @ciderjs/gasnuki/json などのランタイムユーティリティを使用する場合は通常依存(dependencies)に、型生成 CLI や Vite プラグインのみを使用する場合は開発依存(devDependencies)にインストールしてください。
# pnpm
pnpm add @ciderjs/gasnuki
# npm
npm install @ciderjs/gasnuki
# yarn
yarn add @ciderjs/gasnuki
クイックスタート
1. サーバーサイドコードの作成
デフォルトではプロジェクトルート配下の server ディレクトリ内の .ts ファイルが解析対象となります。
export function doGet() {
return HtmlService.createTemplateFromFile('index').evaluate();
}
export function sayHello(name: string): string {
return `Hello, ${name}!`;
}
2. 型定義ファイルの生成
CLI を実行して型定義ファイル(デフォルト:types/appsscript.ts)を生成します。
pnpm exec gasnuki
3. tsconfig.json の設定
生成された型定義ディレクトリが TypeScript コンパイラに認識されるよう、tsconfig.json(または tsconfig.app.json)の include に出力先ディレクトリを追加します。
{
"compilerOptions": {
"strict": true
},
"include": ["src", "types"]
}
4. クライアントサイドからの呼び出し
生成された型定義により、グローバルな google.script.run、または @ciderjs/gasnuki/promise のラッパー関数から型安全にサーバーサイド関数を呼び出せます。
import { getPromisedServerScripts } from '@ciderjs/gasnuki/promise';
import type { ServerScripts } from '../types/appsscript';
// Promise ラッパーを使用する場合(推奨)
const serverScripts = getPromisedServerScripts<ServerScripts>();
async function main() {
const message = await serverScripts.sayHello('Alice');
console.log(message);
}
// グローバル API (google.script.run) を直接使用する場合も型推論が有効
google.script.run
.withSuccessHandler((message) => {
console.log(message); // string 型として推論される
})
.sayHello('Alice');
基本的な使い方
設定ファイル (gasnuki.config.*) の作成
プロジェクトルートに設定ファイルを配置することで、CLI および Vite プラグインの双方で共通の設定を利用できます。以下の順序で最初に発見されたファイルが読み込まれます:
gasnuki.config.ts -> gasnuki.config.mts -> gasnuki.config.cts -> gasnuki.config.js -> gasnuki.config.mjs -> gasnuki.config.cjs
import { defineConfig } from '@ciderjs/gasnuki';
export default defineConfig({
srcDir: './src/server',
outDir: './types',
outputFile: 'appsscript.ts',
cache: true,
});
Vite プラグインによる開発時の自動型生成
vite.config.ts に @ciderjs/gasnuki/vite の gasnuki() を登録すると、vite dev(vite serve)の起動時および srcDir 配下のファイル変更時に 300ms のデバウンス処理を経て型定義が自動生成されます。
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import { gasnuki } from '@ciderjs/gasnuki/vite';
export default defineConfig({
plugins: [
react(),
gasnuki({
srcDir: './src/server',
outDir: './types',
outputFile: 'appsscript.ts',
}),
],
});
CLI リファレンス
コマンド構文
gasnuki [options]
# ソースディレクトリと出力先を指定して実行する例
npx gasnuki -s src/server -o src/types -f gas.d.ts
# ファイル監視モードで起動する例
npx gasnuki --watch
CLI 実行時の設定は 1. コマンドライン引数 > 2. 設定ファイル (gasnuki.config.*) > 3. デフォルト値 の優先順位でマージされます。
オプション一覧
| オプション | エイリアス | 型 / 指定値 | デフォルト | 説明 |
|---|---|---|---|---|
--project <project> |
-p |
string |
process.cwd() |
プロジェクトルートディレクトリのパス。 |
--srcDir <dir> |
-s |
string |
'server' |
解析対象となる GAS ソースコードのディレクトリパス(プロジェクトルートからの相対パスまたは絶対パス)。 |
--outDir <dir> |
-o |
string |
'types' |
型定義ファイルの出力先ディレクトリパス(プロジェクトルートからの相対パスまたは絶対パス)。 |
--outputFile <file> |
-f |
string |
'appsscript.ts' |
出力する型定義ファイル名。 |
--watch |
-w |
boolean |
false |
srcDir 内のファイル変更を監視し、変更時に自動で型定義を再生成します。 |
--cache |
- | boolean |
true |
MD5 ハッシュによる生成キャッシュを有効化します。 |
--no-cache |
- | boolean |
- | 生成キャッシュを無効化し、強制的に再生成します。 |
--version |
-v |
- | - | バージョン番号を表示します。 |
--help |
-h |
- | - | ヘルプを表示します。 |
API リファレンス
@ciderjs/gasnuki は用途に応じて4つのサブパスエクスポートを提供しています。
| エントリーポイント | 主な用途 | 実行環境 |
|---|---|---|
@ciderjs/gasnuki |
設定定義 (defineConfig)・プログラマティックな型生成 (generateTypes) |
Node.js |
@ciderjs/gasnuki/vite |
Vite 開発サーバー連携プラグイン (gasnuki) |
Node.js (Vite) |
@ciderjs/gasnuki/promise |
google.script.run の Promise ラッパー・ローカルモック機能 |
ブラウザ / クライアント |
@ciderjs/gasnuki/json |
Date 対応・型保持 JSON シリアライズ / デシリアライズ |
GAS サーバー / ブラウザ共通 |
defineConfig(config) / generateTypes(options) (@ciderjs/gasnuki)
export interface GenerateOptions {
project: string;
srcDir: string;
outDir: string;
outputFile: string;
watch: boolean;
cache?: boolean;
}
export type UserConfig = Partial<Omit<GenerateOptions, 'watch' | 'project'>>;
export declare function defineConfig(config: UserConfig): UserConfig;
export declare function generateTypes(options: GenerateOptions): Promise<void>;
defineConfig(config):gasnuki.config.*で設定オブジェクトに型付けを行うヘルパー関数です。generateTypes(options): プログラムから型定義生成を実行する非同期関数です。watch: falseの場合は生成完了後にprocess.exit(0)を呼び出し、watch: trueの場合はchokidarによるファイル監視プロセスを起動します。
| プロパティ / 引数 | 型 | デフォルト | 説明 |
|---|---|---|---|
project |
string |
process.cwd() |
プロジェクトルートディレクトリのパス(GenerateOptions のみ)。 |
srcDir |
string |
'server' |
解析対象のソースディレクトリパス。 |
outDir |
string |
'types' |
型定義ファイルの出力先ディレクトリパス。 |
outputFile |
string |
'appsscript.ts' |
出力する型定義ファイル名。 |
watch |
boolean |
false |
ファイル監視モードの有効・無効(GenerateOptions のみ)。 |
cache |
boolean |
true |
MD5 ハッシュによる生成キャッシュの有効・無効。 |
gasnuki(options?) (@ciderjs/gasnuki/vite)
Vite の開発サーバー起動時(apply: 'serve')に動作するプラグイン関数です(vite build 時は実行されません)。引数の型は UserConfig と同一であり、1. プラグイン引数 options > 2. config.root 直下の gasnuki.config.* > 3. デフォルト設定 の優先順位で解決されます。gasnuki.config.* 自体の変更も検知して自動リロード・再生成を行います。
getPromisedServerScripts<T>(options?) (@ciderjs/gasnuki/promise)
サーバーサイド関数の型定義 T(通常は生成された ServerScripts、省略時は Omit<typeof google.script.run, 'withSuccessHandler' | 'withFailureHandler' | 'withUserObject'>)を型引数に受け取り、各メソッドの戻り値を Promise 化したプロキシオブジェクトを返します。
function getPromisedServerScripts<T>(
options: GetPromisedServerScriptsOptions<T, true>,
): PromisedWithJson<T>;
function getPromisedServerScripts<T>(
options?: GetPromisedServerScriptsOptions<T, false>,
): Promised<T>;
export type Promised<T> = {
[K in keyof T]: T[K] extends (...args: infer A) => infer R
? (...args: A) => Promise<R>
: T[K];
};
export type PromisedWithJson<T> = {
[K in keyof T]: T[K] extends (...args: infer A) => infer R
? (...args: A) => Promise<UnwrapJson<R>>
: T[K];
};
export type PartialScriptType<T> = Partial<Promised<T>>;
export type PartialScriptTypeWithJson<T> = Partial<PromisedWithJson<T>>;
| プロパティ / 引数 | 型 | デフォルト | 説明 |
|---|---|---|---|
mockupFunctions |
PartialScriptType<T> |
{} |
ローカル開発時(google.script.run が存在しない環境)に代替実行されるモック関数のマップ。 |
parseJson |
boolean |
false |
true の場合、文字列の戻り値に対して @ciderjs/gasnuki/json の deserialize() を自動適用し、戻り値の型から JsonString<U> を U にアンラップします。 |
strictMock |
boolean |
true |
ローカル環境で mockupFunctions に未定義のメソッドが呼び出された際の挙動を制御します(true: undefined を返却、false: 警告を出して void を解決)。 |
serialize(data) / deserialize(json) (@ciderjs/gasnuki/json)
シリアライズ前の型 T をコンパイル時に保持する Branded Type(JsonString<T>)と、Date オブジェクトの自動復元機能を提供します。
declare const __brand: unique symbol;
export type JsonString<T> = string & { [__brand]: T };
export declare function serialize<T>(data: T): JsonString<T>;
export declare function deserialize<T>(json: JsonString<T>): T;
| プロパティ / 引数 | 型 | デフォルト | 説明 |
|---|---|---|---|
data |
T |
- | serialize に渡す任意のシリアライズ対象データ。JSON.stringify(data) の結果を JsonString<T> で返却。 |
json |
JsonString<T> |
- | deserialize に渡す JSON 文字列。ISO 8601 UTC 日時文字列を Date インスタンスに自動復元して T を返却。 |
アーキテクチャと動作仕様
型定義生成の抽出・除外・型解決ルール
- 対象と除外ファイル:
<srcDir>/**/*.tsを解析し、*.test.tsおよび*.spec.tsを除外します。プロジェクトルートにtsconfig.app.jsonが存在する場合はそれを優先し、なければtsconfig.jsonを参照します。 - 抽出対象: トップレベルの関数宣言(
function foo() {}、exportの有無を問わず、export default functionも対応)、関数式・アロー関数で初期化された変数宣言(const foo = () => {})、およびinterface/type宣言。JSDoc コメントや Branded Type(unique symbol)もそのまま保持されます。 - 除外対象:
- アンダースコア(
_)で終わるプライベート識別子(privateFunc_,PrivateInterface_,PrivateType_)。ただし公開関数の引数・戻り値から参照されている内部型は型整合性維持のためインライン展開されます。 - GAS のシンプルトリガー予約関数(
onOpen,onEdit,onInstall,onSelectionChange,doGet,doPost)。
- アンダースコア(
- 依存する型の解決:
srcDir内の型:生成ファイル内にインライン展開されます。srcDir外のローカルファイルの型:outDirからの相対パスを計算し、import type { ... } from '...'を生成します。node_modules内の外部パッケージの型:package.json(exports,types/typings)を解析してインポート文を生成します。@types/xxxは自動的にxxxへ変換され、@types/google-apps-scriptのようなアンビエント宣言は不要なimportを生成せずグローバル参照(例:SpreadsheetApp.Sheet)として出力します。Pick<T, K>/Omit<T, K>:プロパティを解決したインラインのオブジェクト型リテラル{ ... }に単純化して出力します。
- 生成キャッシュ機構: ソースファイル群のパスと全文から MD5 ハッシュを計算し、前回生成時から変更がなく出力ファイルが存在する場合は再生成をスキップします。
getPromisedServerScripts の実行環境判定と分岐仕様
- GAS 本番環境 (
'google' in globalThis && google?.script?.runが真の場合):mockupFunctionsの有無にかかわらず、常に実際のgoogle.script.runを呼び出します。メソッドが存在しない場合は同期的にError("Method <methodName> not found in AppsScript.")をスローします。parseJson: trueかつサーバーからの戻り値がstringの場合、自動的にdeserialize()でパースして resolve します(不正な JSON 文字列の場合はエラーを握りつぶし元の文字列をそのまま resolve します)。
- ローカル開発環境 (
google.script.runが存在しない場合):mockupFunctionsに該当メソッドが定義されている場合はそれを呼び出します(parseJson: trueでモックがstringを返した場合はdeserialize()を適用し、オブジェクトを直接返した場合はそのまま返します)。- 未定義の場合、
strictMock: true(デフォルト)ではプロパティアクセス時にundefinedを返し(呼び出し時にTypeError)、strictMock: falseでは[gasnuki] Warning: Called undefined mock function '<methodName>'. Falling back to void.を警告出力してundefinedを resolve します。
deserialize における Date 自動復元の仕様
deserialize 内部のカスタム reviver(dateReviver)は、文字列値が厳密な ISO 8601 UTC 形式(正規表現 /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}.\d{3}Z$/)に一致し、かつ有効な日付である場合のみ、ネストされたオブジェクトや配列要素を含めて Date インスタンスへ変換します。単なる日付文字列('2023-01-01')や不正な日時、オブジェクトのキー名に含まれる日時文字列は文字列のまま保持されます。
生成される型定義ファイルの構造
gasnuki が生成するファイル(デフォルト:types/appsscript.ts)には、外部型インポート、抽出されたインターフェース、export type ServerScripts、および declare global { const google: GoogleClientSideApi; }(google.script.run, google.script.url, google.script.history の完全な型定義)が出力されます。
export type ServerScripts = {
sayHello(name: string): string;
};
export declare interface GoogleClientSideApi {
script: {
run: RemoveReturnType<ServerScripts> & {
[key: string]: (...args: any[]) => any;
withSuccessHandler: <T = string | number | boolean | undefined, U = any>(
callback: (returnValues: T, userObject?: U) => void,
) => _AppsScriptRun;
withFailureHandler: <U = any>(
callback: (error: Error, userObject?: U) => void,
) => _AppsScriptRun;
withUserObject: <U = any>(userObject: U) => _AppsScriptRun;
};
url: {
getLocation: (callback: (location: _WebAppLocationType) => void) => void;
};
history: {
push: _AppsScriptHistoryFunction;
replace: _AppsScriptHistoryFunction;
setChangeHandler: (
callback: (e: { state: object; location: _WebAppLocationType }) => void,
) => void;
};
};
}
declare global {
const google: GoogleClientSideApi;
}
実践レシピ・連携例
ローカル開発用のモック設定と切り替え
フロントエンド開発時にモック関数を定義しておくことで、clasp push を行わずに vite dev 上で UI の動作確認を行えます。
import {
getPromisedServerScripts,
type PartialScriptType,
} from '@ciderjs/gasnuki/promise';
import type { ServerScripts } from '../../types/appsscript';
export const mockupScripts: PartialScriptType<ServerScripts> = {
sayHello: async (name) => {
await new Promise((resolve) => setTimeout(resolve, 300));
return `Hello, ${name}! (mock)`;
},
};
export const serverScripts = getPromisedServerScripts<ServerScripts>({
mockupFunctions: mockupScripts,
strictMock: true,
});
serialize と parseJson: true を組み合わせた Date 型の通信
GAS サーバー側で @ciderjs/gasnuki/json の serialize を使用してデータを返し、クライアント側で parseJson: true を有効化することで、型定義の再生成からクライアントでのデシリアライズまで一貫して型安全に扱えます。
import { serialize } from '@ciderjs/gasnuki/json';
export interface UserProfile {
id: number;
name: string;
registeredAt: Date;
}
export function fetchUserProfile(id: number) {
const profile: UserProfile = {
id,
name: 'Alice',
registeredAt: new Date(),
};
// 戻り値の型は JsonString<UserProfile> として推論・抽出される
return serialize(profile);
}
import { getPromisedServerScripts } from '@ciderjs/gasnuki/promise';
import { serialize } from '@ciderjs/gasnuki/json';
import type { ServerScripts } from '../../types/appsscript';
export const serverScripts = getPromisedServerScripts<ServerScripts>({
parseJson: true,
mockupFunctions: {
fetchUserProfile: async (id) =>
serialize({
id,
name: 'Mock Alice',
registeredAt: new Date(),
}),
},
});
async function loadProfile() {
// parseJson: true により、戻り値は JsonString<UserProfile> ではなく UserProfile 型に自動変換される
const profile = await serverScripts.fetchUserProfile(1);
console.log(profile.name); // string
console.log(profile.registeredAt.toISOString()); // Date インスタンスとして扱える
}
制限事項と注意点
- ESLint / Biome 等のリンター設定: 自動生成される
types/appsscript.tsには、google.script.runの柔軟な型定義のためにanyが含まれます。プロジェクトで@typescript-eslint/no-explicit-anyや Biome のnoExplicitAnyルールを有効にしている場合は、生成先のファイルをリント除外(ignore)するか、対象ファイルのルールを無効化してください。
import tseslint from 'typescript-eslint';
export default tseslint.config(
{
files: ['types/appsscript.ts'],
rules: {
'@typescript-eslint/no-explicit-any': 'off',
},
},
);
- Vite ビルド時の型生成:
@ciderjs/gasnuki/viteプラグインは開発サーバー専用(apply: 'serve')です。CI や本番ビルド(vite build)の際には、事前にgasnukiCLI コマンドを実行して型定義ファイルを最新化してからtscおよびビルドを実行してください。
ライセンス
MIT License