他の導入ガイド(全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)にインストールしてください。

.sh
# pnpm
pnpm add @ciderjs/gasnuki

# npm
npm install @ciderjs/gasnuki

# yarn
yarn add @ciderjs/gasnuki

クイックスタート

1. サーバーサイドコードの作成

デフォルトではプロジェクトルート配下の server ディレクトリ内の .ts ファイルが解析対象となります。

server/code.ts
.ts
export function doGet() {
  return HtmlService.createTemplateFromFile('index').evaluate();
}

export function sayHello(name: string): string {
  return `Hello, ${name}!`;
}

2. 型定義ファイルの生成

CLI を実行して型定義ファイル(デフォルト:types/appsscript.ts)を生成します。

.sh
pnpm exec gasnuki

3. tsconfig.json の設定

生成された型定義ディレクトリが TypeScript コンパイラに認識されるよう、tsconfig.json(または tsconfig.app.json)の include に出力先ディレクトリを追加します。

tsconfig.json
.json
{
  "compilerOptions": {
    "strict": true
  },
  "include": ["src", "types"]
}

4. クライアントサイドからの呼び出し

生成された型定義により、グローバルな google.script.run、または @ciderjs/gasnuki/promise のラッパー関数から型安全にサーバーサイド関数を呼び出せます。

src/main.ts
.ts
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

gasnuki.config.ts
.ts
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 のデバウンス処理を経て型定義が自動生成されます。

vite.config.ts
.ts
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 リファレンス

コマンド構文

.sh
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)

index.d.ts
.ts
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 化したプロキシオブジェクトを返します。

promise.d.ts
.ts
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 オブジェクトの自動復元機能を提供します。

json.d.ts
.ts
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)もそのまま保持されます。
  • 除外対象:
    1. アンダースコア(_)で終わるプライベート識別子(privateFunc_, PrivateInterface_, PrivateType_)。ただし公開関数の引数・戻り値から参照されている内部型は型整合性維持のためインライン展開されます。
    2. 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 の実行環境判定と分岐仕様

  1. 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 します)。
  2. ローカル開発環境 (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 の完全な型定義)が出力されます。

types/appsscript.ts
.ts
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 の動作確認を行えます。

src/lib/gas.ts
.ts
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 を有効化することで、型定義の再生成からクライアントでのデシリアライズまで一貫して型安全に扱えます。

src/server/code.ts
.ts
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);
}
src/lib/gas.ts
.ts
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)するか、対象ファイルのルールを無効化してください。
eslint.config.js
.js
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)の際には、事前に gasnuki CLI コマンドを実行して型定義ファイルを最新化してから tsc およびビルドを実行してください。

ライセンス

MIT License

関連する技術記事