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

## はじめに

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

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

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

## claspのメリット

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

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

## 環境設定

### 前提条件

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

### インストール

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

```bash
npm install -g @google/clasp
```

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

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

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

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

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

### ログイン

claspを使用するには、自分のGoogleアカウントで認証を行う必要があります。

```bash
clasp login
```

このコマンドを実行すると、ブラウザが開き、Googleアカウントでの認証が求められます。認証が成功すると、ローカルの`.clasprc.json`ファイルに認証情報が保存されます。

## 基本的な使い方

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

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

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

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

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

```bash
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プロジェクトをローカルにクローンするには：

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

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

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

### ファイルの同期

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

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

```bash
clasp push
```

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

```bash
clasp push --watch
```

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

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

```bash
clasp pull
```

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

```bash
clasp pull --versionNumber 10
```

### プロジェクトを開く

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

```bash
clasp open-script
```

### バージョン管理

#### バージョンの作成

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

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

#### バージョンの一覧表示

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

```bash
clasp list-versions
```

### デプロイメント管理

#### デプロイメントの作成

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

```bash
clasp create-deployment --description "Initial deployment"
```

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

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

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

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

```bash
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`という設定ファイルを使用します。公式リポジトリによると、このファイルには以下の設定が含まれます：

```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`（オプション）: 最初にプッシュするファイルの順序指定

## トラブルシューティング

### よくある問題と解決方法

#### 認証エラー

```bash
Error: Command failed: clasp login
```

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

#### プッシュエラー

```bash
Error: Command failed: clasp push
```

解決策：
- `.clasprc.json`の権限を確認
- 無効なファイルタイプがないか確認
- 強制的にプッシュ: `clasp push --force`

#### Node.jsのバージョン問題

claspはNode.js 22.0.0以上が必要です。バージョンを確認し、必要に応じて更新してください：

```bash
node -v
# Node.jsが古い場合の更新（Windowsを除く）
npm install -g npm  # npmとnpxを更新
npx n latest  # nパッケージを使用してnodeを更新
```

### デバッグ方法

内部ログを有効にしてデバッグするには、環境変数`DEBUG=clasp:*`を設定します：

```bash
DEBUG=clasp:* clasp pull  # 詳細なデバッグ出力を表示
```

## おわりに

claspを使うことで、Google Apps Scriptの開発体験は大きく向上します。ローカル開発環境、バージョン管理、チーム開発のしやすさなど、多くのメリットがあります。

この記事で紹介した基本的なコマンドとワークフローを活用して、より効率的なGAS開発を始めてみてください。また、公式のコードラボも用意されていますので、実践的な学習に役立ててください：[clasp codelab](https://g.co/codelabs/clasp)

## TypeScriptでの開発

clasp 3.xではTypeScript直接サポートが削除されたことがGitHubリポジトリに明記されています。公式情報によると、TypeScriptプロジェクトではTypeScriptとRollupなどのバンドラーを組み合わせて使用することが推奨されています。

### TypeScript開発のアプローチ

TypeScript開発用のテンプレートプロジェクトもGitHubで公開されています。これらを利用すると、簡単に開発環境を構築できます：

- [apps-script-typescript-rollup-starter](https://github.com/sqrrrl/apps-script-typescript-rollup-starter)
- [apps-script-engine-template](https://github.com/WildH0g/apps-script-engine-template)
- [clasp-typescript-template](https://github.com/tomoyanakano/clasp-typescript-template)

## 参考リンク

- [clasp GitHub リポジトリ](https://github.com/google/clasp)
- [Google Apps Script API ドキュメント](https://developers.google.com/apps-script/api/)
- [clasp codelab（公式チュートリアル）](https://g.co/codelabs/clasp)
- [@types/google-apps-script（TypeScript型定義）](https://www.npmjs.com/package/@types/google-apps-script)
- [apps-script-typescript-rollup-starter（TypeScriptテンプレート）](https://github.com/sqrrrl/apps-script-typescript-rollup-starter)