他の導入ガイド(全7件)

GAS / 導入ガイド

@ciderjs/gasbombe

GASに特化したTypeScript/JavaScriptプロジェクトをCLIで生成

npx @ciderjs/gasbombe
このページの内容

@ciderjs/gasbombe は、Google Apps Script (GAS) プロジェクトをモダンなローカル開発環境で迅速に構築するための TypeScript 製プロジェクトジェネレーター(CLI および Node.js API)です。テンプレートの展開、Apps Script プロジェクトとの接続設定(.clasp.json)、依存パッケージのインストール、Git リポジトリの初期化までを一貫して行います。

概要と特徴

GAS のローカル開発環境を一から構築するには、バンドラ(Rolldown / Vite)、リンター(Biome)、テスト環境(Vitest)、型定義、および @google/clasp の設定など多岐にわたる構成が必要です。@ciderjs/gasbombe は、用途に応じた8種類のテンプレートと AI コーディングエージェント向けの設計規約(.agents/)を統合し、即座に開発を始められる環境を生成します。

  • 対話型 CLI と非対話実行の両対応: 質問に答えるだけでセットアップが完了する対話モードと、CI/CD やスクリプトから一括生成できるコマンドラインオプション指定をサポートしています。
  • 全8種類のプロジェクトテンプレート: サーバーサイド専用(TypeScript / JavaScript)から、React 19 / Vue 3 / HTML+JS を用いた Web アプリ(HtmlService)まで用途に応じて選択できます。
  • CiderJS エコシステム統合: @ciderjs/gasnuki(型保持 JSON シリアライズとクライアント向け型生成)、@ciderjs/city-gas(Zod スキーマによるファイルベースルーティング)、@ciderjs/vitest-plugin-gas-mock(GAS グローバル API モック)、@ciderjs/clasp-auth(GitHub Secrets への認証情報登録)を統合したテンプレートを用意しています。
  • モダンなツールチェーン: サーバーサイドのバンドルに Rolldown、フロントエンドの単一 HTML バンドルに Vite、リンター・フォーマッターに Biome、テストランナーに Vitest を採用しています。
  • AI コーディングエージェント最適化: GAS 特有のサンドボックス制約やアンチパターンを定義した .agents/ ディレクトリおよび各 AI ツール(Claude Code, Cursor, GitHub Copilot, Gemini, OpenAI Codex 等)用の設定ファイルが、選択したテンプレートに合わせて最適化された状態で出力されます。

動作要件

  • Node.js: >= 22
  • パッケージマネージャー: pnpm, npm, yarn のいずれか
  • Git (任意): Git リポジトリの初期化(デフォルト有効)を行う場合は git コマンドおよび Git のユーザー設定(user.name, user.email)が必要です。
  • Google Apps Script 連携 (任意): clasp によるプロジェクト新規作成(create)や一覧選択(list)、コードの反映(push)を行う場合は、事前に @google/clasp でログイン(npx @google/clasp login)しておく必要があります。

インストール

pnpm dlx または npx を使用してインストールせずに直接実行するか、グローバル環境・開発依存関係(プログラマティック API 利用時)としてインストールします。

.sh
# pnpm dlx で直接実行(推奨)
pnpm dlx @ciderjs/gasbombe@latest

# npx で直接実行
npx @ciderjs/gasbombe@latest

# グローバルインストールする場合
pnpm add -g @ciderjs/gasbombe

# Node.js API としてプロジェクトに導入する場合
pnpm add -D @ciderjs/gasbombe

※ プログラマティック API として利用する場合、@inquirer/prompts, commander, consola, ejs, glob が peerDependencies に指定されています。ピア依存関係を自動インストールしない環境では、これらもあわせてインストールしてください。

クイックスタート

1. 対話モードでのプロジェクト作成

オプションを指定せずに実行すると、以下の順序で対話プロンプトが表示されます(コマンドライン引数で指定済みの項目はスキップされます)。

  1. Project name: 生成するプロジェクト名(. を指定するとカレントディレクトリに展開)
  2. Project template: 使用するテンプレート(8種類から選択)
  3. Apps Script project setup: .clasp.json の設定方法(create / list / input / skip)
  4. Apps Script project ID: 上記で input を選んだ場合のみ、Script ID を手入力
  5. Package manager: 依存関係のインストールに使用するパッケージマネージャー(npm / pnpm / yarn / skip)
  6. Initialize Git repository: Git リポジトリを初期化するかどうか(デフォルト: Yes)
.sh
pnpm dlx @ciderjs/gasbombe@latest

2. ローカル開発の開始

クライアント付きテンプレート(react, react-ciderjs, vue, vue-ciderjs, html-js)では、生成されたディレクトリへ移動して Vite 開発サーバーを起動できます(サーバーサイド専用テンプレートには dev スクリプトはありません)。

.sh
cd my-gas-app
pnpm dev

3. 品質チェック・ビルド・GAS への反映

リント、単体テスト、およびバンドルビルドを実行した上で、clasp push により dist/ の成果物を GAS プロジェクトへアップロードします。

.sh
pnpm run check
pnpm test
pnpm run build
pnpm run push

基本的な使い方

テンプレート一覧とディレクトリ構成

テンプレート名 構成区分 サーバー側 フロントエンド 主な同梱パッケージ・特徴
server-ts サーバーのみ TypeScript なし Rolldown, rolldown-plugin-remove-export, Vitest, Biome
server-js サーバーのみ JavaScript なし Rolldown, rolldown-plugin-remove-export, Vitest, Biome
server-ciderjs サーバーのみ TypeScript なし server-ts の構成 + @ciderjs/vitest-plugin-gas-mock, @ciderjs/clasp-auth
react サーバー + クライアント TypeScript React 19 + TS Vite, vite-plugin-singlefile, vite-plugin-google-apps-script, Rolldown, Testing Library, Vitest, Biome
react-ciderjs サーバー + クライアント TypeScript React 19 + TS react の構成 + @ciderjs/gasnuki, @ciderjs/city-gas, @ciderjs/vitest-plugin-gas-mock, @ciderjs/clasp-auth, Zod
vue サーバー + クライアント TypeScript Vue 3 + TS Vite, vite-plugin-singlefile, vite-plugin-google-apps-script, Rolldown, @vue/test-utils, vue-tsc, Vitest, Biome
vue-ciderjs サーバー + クライアント TypeScript Vue 3 + TS vue の構成 + @ciderjs/gasnuki, @ciderjs/city-gas, @ciderjs/vitest-plugin-gas-mock, @ciderjs/clasp-auth, Zod
html-js サーバー + クライアント JavaScript HTML / CSS / JS Vite, vite-plugin-singlefile, vite-plugin-google-apps-script, Rolldown, Testing Library (DOM), Vitest, Biome

サーバー専用テンプレート (server-ts, server-js, server-ciderjs) の構成:
サーバーサイドのソースコードは src/ に配置されます。

.txt
my-gas-app/
├── src/
│   ├── modules/
│   │   └── hello.ts          # 分割されたモジュール (.js の場合は hello.js)
│   ├── app.ts                # GAS エントリーポイント (.js の場合は app.js)
│   └── appsscript.json       # GAS マニフェストファイル
├── tests/
│   └── app.test.ts           # Vitest 単体テスト
├── .agents/                  # AI エージェント向けルール・スキル定義
├── .clasp.json               # clasp 設定ファイル (rootDir: "dist")
├── biome.json                # Biome 設定
├── package.json
├── rolldown.config.ts        # Rolldown バンドル設定 (.js の場合は .mjs)
├── tsconfig.json             # TypeScript 設定 (server-js には含まれません)
└── vitest.config.ts          # Vitest 設定 (.js の場合は .js)

クライアント付きテンプレート (react, react-ciderjs, vue, vue-ciderjs, html-js) の構成:
GAS サーバー側のコードは server/、フロントエンドのコードは src/ に分離されています。

.txt
my-gas-app/
├── server/
│   ├── modules/
│   │   └── hello.ts          # GAS サーバー側モジュール
│   ├── app.ts                # GAS エントリーポイント (doGet 等を定義)
│   └── appsscript.json       # GAS マニフェストファイル (webapp 設定含む)
├── src/
│   ├── lib/
│   │   ├── parameters.ts     # doGet から渡される初期パラメータ取得処理 (html-js は index.html 内)
│   │   └── server.ts         # gasnuki RPC クライアント・モック定義 (*-ciderjs のみ)
│   ├── pages/                # city-gas ページコンポーネント (*-ciderjs のみ)
│   └── main.tsx              # フロントエンドエントリーポイント (vue は main.ts, html-js は main.js)
├── tests/                    # サーバー・フロントエンド双方のテスト
├── types/
│   └── appsscript/
│       ├── server.ts         # WebAppParams / ServerParams 型定義
│       └── client.ts         # gasnuki が自動生成する ServerScripts 型 (*-ciderjs で生成)
├── .agents/                  # AI エージェント向けルール・スキル定義
├── .github/workflows/
│   └── appsscript.yml        # GAS 自動 push 用 GitHub Actions ワークフロー (*-ciderjs のみ)
├── .clasp.json               # clasp 設定ファイル (rootDir: "dist")
├── .env                      # デプロイ更新用環境変数 (GAS_DEPLOYMENT_ID)
├── gasnuki.config.ts         # gasnuki 設定 (*-ciderjs のみ)
├── index.html                # フロントエンド HTML テンプレート
├── rolldown.config.ts        # サーバーコード用 Rolldown 設定 (.js の場合は .mjs)
└── vite.config.ts            # フロントエンド用 Vite 設定 (html-js は vite.config.js / vitest.config.js)

パスエイリアスとして、@/*(./src/*、全テンプレート対応)および ~/*(./*、server-js を除く全テンプレート対応)が設定されています。

clasp のセットアップ方法 (--clasp)

初期状態のテンプレートでは .clasp.json の rootDir に "dist"、scriptId にプレースホルダー "{{ input your script id of apps-script }}" が設定されています。

指定値 動作詳細
create <pkg-dlx> @google/clasp status でログイン確認後、clasp create --title "<projectName>" --type standalone を実行して新規 GAS プロジェクトを作成し、出力から取得した scriptId で .clasp.json を更新します。
list <pkg-dlx> @google/clasp status でログイン確認後、clasp list を実行して既存プロジェクト一覧を取得し、対話プロンプトで選択したプロジェクトの scriptId で .clasp.json を更新します。
input 入力された既存の Script ID で .clasp.json の scriptId を更新します(空文字の場合は更新しません)。
skip clasp コマンドを実行せず、テンプレート初期状態の .clasp.json(プレースホルダーのまま)を残します。

生成プロジェクトの package.json スクリプト一覧

内部スクリプトの呼び出しには cross-var $npm_execpath run ... が使用されており、npm, pnpm, yarn のいずれから実行しても同じランナーで統一処理されます。

スクリプト 対象テンプレート 実行コマンドと内容
dev クライアント付き全般 vite を実行し、ローカル開発サーバーを起動します。
check 全テンプレート biome check --write を実行し、リント・フォーマット・インポート整理と自動修正を行います。
test 全テンプレート vitest run --coverage を実行し、単体テストとカバレッジ計測を行います。
generate react-ciderjs, vue-ciderjs gasnuki を実行し、server/ の関数から types/appsscript/client.ts を生成します。
tsc vue, vue-ciderjs node ./node_modules/@typescript/v7/bin/tsc --noEmit でサーバー側の型チェックを実行します。
build:front クライアント付き全般 フロントエンドの型チェック・コード生成・vite build を実行します。
build:server クライアント付き全般 rolldown -c でサーバーコードをバンドルし、cpy server/*.json dist/ でマニフェストをコピーします。
build 全テンプレート サーバー専用は型チェック・Rolldown・JSON コピーを実行。クライアント付きは rimraf dist 後に build:front と build:server を順に実行します。
push 全テンプレート clasp push を実行し、dist/ の内容を GAS へアップロードします。
deploy 全テンプレート clasp create-deployment を実行し、新しいデプロイを作成します。
update 全テンプレート dotenv cross-var "clasp update-deployment $GAS_DEPLOYMENT_ID" を実行し、.env のデプロイ ID を使って既存デプロイを更新します。
auth *-ciderjs 全般 clasp-auth upload を実行し、clasp 認証情報と .clasp.json を GitHub Secrets にアップロードします。
preview:local クライアント付き全般 vite preview でビルド成果物をローカル確認します。
preview:web クライアント付き全般 clasp open-web-app でデプロイ済みの Web アプリをブラウザで開きます。

CLI リファレンス

コマンド構文

.sh
gasbombe [options]

# 非対話モードでの完全自動実行例
pnpm dlx @ciderjs/gasbombe -n my-gas-project -p pnpm -t react-ciderjs -c skip --git --skipInstall

すべての対話プロンプトを省略して実行するには、--name(. の場合はディレクトリが空であること)、--template、--clasp(create または skip)、--pkg(または --clasp skip --skipInstall)、および --git / --skipGit を指定します。

オプション一覧

オプション エイリアス 型 / 指定値 デフォルト 説明
--name -n string ([projectName]) なし(対話入力) 生成するプロジェクト名(半角英数字・-・_、またはカレントディレクトリ .)。
--template -t server-ts | server-js | server-ciderjs | react | react-ciderjs | vue | vue-ciderjs | html-js なし(対話入力) 使用するプロジェクトテンプレート。
--clasp -c create | list | input | skip なし(対話入力) .clasp.json のセットアップ方法。
--pkg -p npm | pnpm | yarn なし(対話入力) 依存関係のインストールと clasp 実行コマンド(npx / pnpm dlx / yarn dlx)の決定に使用。
--skipInstall - boolean false 依存パッケージのインストールをスキップします。
--git -g boolean (true | false または値省略) なし(対話確認) Git リポジトリの初期化と初回コミット("Initial commit from gasbombe")を制御します。
--skipGit - boolean false Git リポジトリの初期化をスキップします(--git より優先)。
--version -v - - バージョン番号を表示します。
--help -h - - ヘルプを表示します。

不正な値を引数に渡した場合は、Invalid project name, Invalid project template, Invalid clasp option, Invalid package manager のいずれかのエラーをスローして終了します。また、--pkg が未指定かつ --clasp が create / list 以外で --skipInstall が指定されている場合は、プロンプトを表示せず自動で npm が選択されます。

API リファレンス

@ciderjs/gasbombe は ESM(dist/index.mjs)および CommonJS(dist/index.cjs)のモジュールとして generateProject, runCommand, isWindows をエクスポートしています。

generateProject(options)

指定されたオプションでテンプレートを展開し、clasp 設定、依存関係インストール、Git 初期化を実行します。

index.d.ts
.ts
export type PackageManager = 'npm' | 'pnpm' | 'yarn';

export type TemplateType =
  | 'server-ts'
  | 'server-js'
  | 'server-ciderjs'
  | 'react'
  | 'react-ciderjs'
  | 'vue'
  | 'vue-ciderjs'
  | 'html-js';

export type ClaspOption = 'create' | 'list' | 'input' | 'skip';

export interface ProjectOptions {
  projectName: string;
  packageManager: PackageManager;
  templateType: TemplateType;
  clasp: ClaspOption;
  claspProjectId?: string | undefined;
  install: boolean;
  git?: boolean;
}

export declare function generateProject(options: ProjectOptions): Promise<void>;
プロパティ / 引数 型 デフォルト 説明
projectName string - 生成先のディレクトリ名(process.cwd() からの相対パス)。"." を指定するとカレントディレクトリに展開します。
packageManager 'npm' | 'pnpm' | 'yarn' - 依存関係のインストールと clasp 実行コマンドの決定に使用するパッケージマネージャー。
templateType TemplateType - 展開するテンプレート名。
clasp ClaspOption - .clasp.json のセットアップ方法('create' | 'list' | 'input' | 'skip')。
claspProjectId string | undefined undefined clasp: 'input' の際に .clasp.json へ書き込む Script ID。
install boolean - true の場合、ファイル生成後に <packageManager> install を実行します。
git boolean true true の場合、git init と初回コミットを実行します。

runCommand(command, args, cwd, capture?) / isWindows()

  • runCommand(command: string, args: string[], cwd: string, capture?: boolean): Promise<string>
    child_process.spawn を用いて外部コマンドを実行します。command に空白が含まれる場合(例:"pnpm dlx")は自動的に分割して spawn に渡します。capture: false(デフォルト)では stdio: "inherit" で実行し空文字列 "" を resolve、capture: true では stdio: "pipe" で実行し stdout.trim() を resolve します。Windows 環境では自動的に shell: true が設定され、終了コードが 0 以外の場合は Error で reject します。
  • isWindows(): boolean
    process.platform === "win32" かどうかを判定して返します。

アーキテクチャと動作仕様

サーバーサイドのバンドルと関数公開 (rolldown-plugin-remove-export)

GAS の V8 ランタイムは ES Modules の export { ... } 構文をそのままでは実行できません。生成されたプロジェクトでは、Rolldown でエントリーポイント(src/app.ts または server/app.ts)を dist/app.js に単一ファイルバンドルする際、rolldown-plugin-remove-export によって末尾の export 宣言を自動除去します。

  • GAS のスクリプトエディタ、トリガー、またはクライアントから呼び出したい関数は、エントリーポイントから 名前付きエクスポート(export function ... または export * from ...) として定義します(export default は関数名が失われるため使用禁止)。
  • マニフェストファイル(appsscript.json)はビルド時に cpy コマンドで dist/ へコピーされます。
server/app.ts
.ts
export * from './modules/hello';

export function doGet(e: GoogleAppsScript.Events.DoGet) {
  return HtmlService.createTemplateFromFile('index').evaluate();
}

フロントエンドの単一 HTML バンドルと初期パラメータ受け渡し

クライアント付きテンプレートでは、vite-plugin-google-apps-script と vite-plugin-singlefile を使用し、ビルド時にすべての JS / CSS を単一の dist/index.html にインライン化します。

また、server/app.ts の doGet(e) では HtmlService.createTemplateFromFile('index') を使用し、クエリパラメータや実行ユーザーのメールアドレス(Session.getActiveUser().getEmail())を htmlTemplate.parameters に JSON 文字列として注入します。クライアント側の src/lib/parameters.ts(html-js では index.html 内の <script>)ではスクリプトレット <?!= JSON.stringify(parameters) ?> をパースして取得し、ローカルの Vite 開発サーバー(pnpm dev)実行時には catch 節でモックデータ(mock-user@example.com 等)へ自動フォールバックします。

AI コーディングエージェント対応 (.agents/)

生成されたすべてのプロジェクトには、AI コーディングエージェントが GAS の制約を守ってコードを生成するための指示ファイル群(.agents/AGENTS.md, CLAUDE.md, CODEX.md, GEMINI.md, .cursor/rules/gasbombe.mdc, .github/copilot-instructions.md)が含まれます。

テンプレート区分 共通ルール・スキルに加えて追加されるルール (.agents/rules/) 追加されるスキル (.agents/skills/)
全テンプレート共通 gas-constraints.md, coding-style.md, tsconfig-and-types.md, antipatterns.md gas-test, gas-build-and-push, gas-deploy
server-ts, server-js server-architecture.md(関数公開規約、セルフクリーニングトリガー設計等) gas-add-server-function/SKILL.md
react, vue, html-js spa-architecture.md(単一 HTML バンドル、Vite プラグイン順序、非同期通信) gas-add-ui-component/SKILL.md
server-ciderjs server-architecture.md, ciderjs-architecture.md, gasnuki-types.md gas-add-server-function/SKILL.md, gas-add-endpoint/SKILL.md
react-ciderjs, vue-ciderjs spa-architecture.md, ciderjs-architecture.md, gasnuki-types.md gas-add-ui-component/SKILL.md, gas-add-endpoint/SKILL.md

実践レシピ・連携例

初回デプロイと継続更新・GitHub Actions 連携

初回は pnpm run deploy で新規デプロイを作成し、発行されたデプロイ ID をプロジェクトルートの .env ファイルに設定します(サーバー専用テンプレートでは .env を新規作成します)。

.env
.ini
GAS_DEPLOYMENT_ID=AKfycb...

2回目以降は pnpm run update を実行することで、Web アプリの公開 URL を変えずに最新バージョンへ更新できます。また、*-ciderjs テンプレートではローカルで clasp login と gh auth login を済ませた状態で pnpm run auth <owner>/<repo> を実行すると、GitHub Secrets に CLASPRC_JSON と CLASP_JSON が登録され、v* タグの push 時に .github/workflows/appsscript.yml によって自動でチェック・テスト・ビルド・clasp push が実行されます。

モノレポ内のパッケージディレクトリへプログラマティックに展開する

generateProject API を使用して、既存のモノレポ内のサブパッケージへテンプレートを展開するスクリプト例です。

scripts/setup-gas.ts
.ts
import { generateProject } from '@ciderjs/gasbombe';

await generateProject({
  projectName: '.',
  packageManager: 'pnpm',
  templateType: 'vue-ciderjs',
  clasp: 'input',
  claspProjectId: 'your-existing-script-id',
  install: false, // ルートで管理するためスキップ
  git: false, // 既存リポジトリ内のためスキップ
});

制限事項と注意点

  • push や deploy 前のビルド実行: pnpm run push や pnpm run deploy スクリプト自体にはビルド処理が含まれていません。コード変更後は必ず先に pnpm run build を実行して dist/ を更新してください。
  • マニフェスト (appsscript.json) の公開範囲設定: 初期設定では timeZone: "Asia/Tokyo", runtimeVersion: "V8" となっており、クライアント付きテンプレートでは Web アプリ設定が executeAs: "USER_ACCESSING", access: "ANYONE" になっています。本番デプロイ前に組織のセキュリティ要件に合わせて公開範囲を確認・変更してください。
  • clasp エラー時のフォールバック動作: create や list で未ログインエラーや通信エラーが発生した場合でも、エラーログを表示したうえでプロジェクトファイルの生成自体は最後まで続行されます。その場合は生成後に手動で .clasp.json の scriptId を書き換えてください。
  • プログラマティック API (generateProject) 利用時の注意点:
    • プロジェクト名(正規表現 /^(?!.*\.\.)[a-zA-Z0-9_-]+$/)やテンプレート名のバリデーションは CLI 側(src/cli.ts)で行われるため、generateProject を直接呼び出す際は呼び出し側で値を検証してください。
    • projectName が "." 以外で出力先ディレクトリが既に存在する場合は、consola.error を出力して process.exit(1) でプロセス自体が終了します。
    • projectName: "." を指定した場合、対象ディレクトリ内にドット(.)で始まらないファイルやフォルダが1つでも存在すると対話プロンプト(Current directory is not empty. Proceed anyway?)が表示されます。CI 等の非対話環境で "." を指定する場合は対象ディレクトリを空にしておいてください。

ライセンス

MIT License

関連する技術記事