Google Apps Script開発をローカルで行うためのツール「clasp」入門

Posted at 2025-03-11

はじめに

Google Apps Script（GAS）は、Google製品を拡張・自動化するための強力なスクリプト言語です。通常、GASの開発はブラウザ上のスクリプトエディタで行いますが、バージョン管理の難しさやチーム開発における制約など、いくつかの課題があります。

そこで登場するのが「clasp」（Command Line Apps Script Projects）です。claspはGoogleが提供する公式のコマンドラインツールで、ローカル環境でGASプロジェクトを開発できるようにするものです。

この記事では、claspの基本的な使い方から、実際の開発ワークフローまでを自分自身も初心者なので調べながら解説します。

claspのメリット

公式リポジトリに記載されている情報によると、claspを使った開発には次のようなメリットがあります：

ローカル開発 (🗺️ Develop Locally): お気に入りのエディタやIDEを使用して開発できます。ソースコード管理が可能になり、他の開発者とのコラボレーションがしやすくなります。
デプロイメント管理 (🔢 Manage Deployment Versions): プロジェクトの複数のデプロイメントを作成、更新、表示できます。
コード構造化 (📁 Structure Code): script.google.comの平坦なプロジェクトを自動的にフォルダに変換します。
コマンドライン実行 (➡️ Run Apps Script): コマンドラインから直接Apps Scriptを実行できます。

環境設定

前提条件

Node.js 22.0.0以上
npmパッケージマネージャー

インストール

まず、npmを使用してclaspをグローバルにインストールします。

npm install -g @google/clasp

TypeScript開発を行う場合は、Google Apps Scriptの型定義ファイルもインストールすることをお勧めします。

npm install --save-dev @types/google-apps-script

これにより、コードエディタでの入力補完や型チェックが可能になり、開発効率が向上します。

インストールが完了したら、Google Apps Script APIを有効にする必要があります。以下のURLにアクセスしてください：
https://script.google.com/home/usersettings

ページが開いたら、「Google Apps Script API」の設定を探し、有効にしてください。これにより、claspがApps Scriptプロジェクトと通信できるようになります。

基本的な使い方

新しいプロジェクトの作成

新しいGASプロジェクトを作成するには：

clasp create-script --title "My New Project"

このコマンドは、新しいApps Scriptプロジェクトを作成し、必要なファイルをローカルに生成します。

オプションでプロジェクトタイプを指定することもできます：

clasp create-script --type sheets --title "Spreadsheet Extension"

利用可能なタイプ：

standalone（デフォルト）: スタンドアロンスクリプト
docs: Google Docsアドオン
sheets: Google Sheetsアドオン
slides: Google Slidesアドオン
forms: Google Formsアドオン
webapp: Webアプリケーション
api: APIサービス

既存プロジェクトのクローン

既存のApps Scriptプロジェクトをローカルにクローンするには：

clasp clone-script "スクリプトID"

スクリプトIDは、Apps Scriptエディタの「ファイル」>「プロジェクトのプロパティ」で確認できます。また、スクリプトURLからも直接クローンできます：

clasp clone-script "https://script.google.com/d/スクリプトID/edit"

ファイルの同期

ローカルからサーバーへの同期（プッシュ）

ローカルの変更をApps Scriptサーバーに反映させるには：

clasp push

修正を監視して自動的にプッシュするウォッチモードも利用可能です：

clasp push --watch

サーバーからローカルへの同期（プル）

サーバー側の最新バージョンをローカルに取得するには：

clasp pull

特定のバージョンを取得することも可能です：

clasp pull --versionNumber 10

プロジェクトを開く

ブラウザでスクリプトエディタを開くには：

clasp open-script

バージョン管理

バージョンの作成

新しいバージョンを作成するには：

clasp create-version "バージョン説明"

バージョンの一覧表示

プロジェクトのバージョン一覧を表示するには：

clasp list-versions

デプロイメント管理

デプロイメントの作成

スクリプトをデプロイするには：

clasp create-deployment --description "Initial deployment"

特定のバージョンをデプロイすることも可能です：

clasp create-deployment --versionNumber 5 --description "新機能追加"

デプロイメントの一覧表示

デプロイメント一覧を表示するには：

clasp list-deployments

実践的な開発ワークフロー

ここでは、claspを使った実際の開発ワークフローを紹介します。

1. プロジェクトの構造化

claspを使うと、Apps Scriptプロジェクトをフォルダに分けて構造化できます。例えば：

my-gas-project/
├── .clasp.json     # claspの設定ファイル
├── .claspignore    # 無視するファイルの設定
├── appsscript.json # マニフェストファイル
├── src/
│   ├── main.js     # メインの処理
│   ├── utils.js    # ユーティリティ関数
│   └── ui.js       # UI関連の処理
└── tests/
    └── main.test.js # テストコード

TypeScriptを使用する場合は、以下のような構成になります：

my-gas-project/
├── .clasp.json     # claspの設定ファイル
├── .claspignore    # 無視するファイルの設定
├── appsscript.json # マニフェストファイル
├── tsconfig.json   # TypeScript設定ファイル
├── package.json    # npmパッケージ設定
├── src/
│   ├── main.ts     # メインの処理（TypeScript）
│   ├── utils.ts    # ユーティリティ関数
│   └── ui.ts       # UI関連の処理
└── node_modules/
    └── @types/google-apps-script/ # GAS型定義ファイル

2. 無視ファイルの設定

.claspignoreファイルを作成することで、pushするときに無視するファイルを指定できます。例えば：

# すべてのファイルを無視
**/**

# 以下のファイルのみpush対象とする
!appsscript.json
!src/**/*.js
!tests/**/*.js

3. プロジェクト設定ファイル

claspは.clasp.jsonという設定ファイルを使用します。公式リポジトリによると、このファイルには以下の設定が含まれます：

{
  "scriptId": "",       // 必須: スクリプトのID
  "rootDir": "build/",  // オプション: ローカルディレクトリ
  "projectId": "project-id-xxxxxxxxxxxxxxxxxxx", // オプション: GCPプロジェクトID
  "fileExtension": "ts", // オプション: ファイル拡張子
  "filePushOrder": ["file1.ts", "file2.ts"] // オプション: ファイルのプッシュ順序
}

各設定の詳細：

scriptId（必須）: Google Scriptプロジェクトの識別子
rootDir（オプション）: ローカルファイルを保存するディレクトリ
projectId（オプション）: Google Cloud Platformのプロジェクト識別子
fileExtension（オプション）: ローカルスクリプトファイルの拡張子
filePushOrder（オプション）: 最初にプッシュするファイルの順序指定

トラブルシューティング

よくある問題と解決方法

認証エラー

Error: Command failed: clasp login

解決策：

Google Apps Script APIが有効になっているか確認
clasp logoutを実行してから再度clasp loginを試す

プッシュエラー

Error: Command failed: clasp push