claspはいいぞ

久しぶりにGAS（Google Apps Script）を使ったミニマルなツールを作ったのですが、clasp導入のやり方を忘れていたので手順をメモしておきます。

GASはWeb上のスクリプトエディタでサクッと書けるメリットがある一方、エディタの使い勝手が微妙で、スクリプトの機能拡充や複数人開発などをやり始めると早々にしんどい事態に陥ります。

特に変更履歴で差分の判別ができないのは絶望的…

そんなGASのソースコードをローカル環境に落とし、自由度の高い開発スタイルを実現してくれるCLIツールがclaspです。

google/clasp: 🔗 Command Line Apps Script Projects

Google製だよ

claspの導入

というわけで、さっそく導入してみましょう。

npmコマンドでclaspをインストール

まずはclaspをnpmコマンドでインストール。

$ npm i @google/clasp -g
/usr/local/bin/clasp -> /usr/local/lib/node_modules/@google/clasp/src/index.js
npm WARN inquirer-autocomplete-prompt@1.0.1 requires a peer of inquirer@^5.0.0 || ^6.0.0 but none is installed. You must install peer dependencies yourself.

+ @google/clasp@2.3.0

npm未導入の場合は、Homebrew経由でインストールするのがよろしいかと思います。

Googleアカウント連携

続いてGoogleアカウントと連携します。

$ clasp login
Warning: You seem to already be logged in *globally*. You have a ~/.clasprc.json
Logging in globally...
🔑 Authorize clasp by visiting this url:
https://accounts.google.com/o/oauth2/v2/auth?access_type=offline&scope=xxxxxxxxxx

clasp loginコマンドを叩くとブラウザで認証画面が開くので

Googleアカウントへのアクセスを許可しましょう。

Authorization successful.

Google Apps Script APIを有効化する

これを忘れると後述のclasp pushなどでエラーが起きます。

? Give a description:  
User has not enabled the Apps Script API. Enable it by visiting https://script.google.com/home/usersettings then retry. If you enabled this API recently, wait a few minutes for the action to propagate to our systems and retry.

Google Apps Scriptの「設定」画面へアクセスして
https://script.google.com/home/usersettings

オフになっている「Google Apps Script API」項目をクリック。

設定を「オン」にします。

以上でclaspの導入は完了です。
簡単ですね。

よく使うコマンド

実際にGASプロジェクトをローカル環境に落とすなど、比較的よく使うコマンドを紹介しておきます。

Clone

すでに存在しているGASプロジェクトがある場合は、clasp cloneでクローンできます。引数に対象のスクリプトIDを指定しましょう。

$ clasp clone <SCRIPT_ID>

これでGASプロジェクトのソースコードがローカル環境でいじれるようになりました。

Warning: files in subfolder are not accounted for unless you set a '.claspignore' file.
Cloned 8 files.
└─ character.js
└─ main.js
└─ menu.js
└─ pr.js
└─ random.js
└─ appsscript.json
└─ channel.js
└─ reviewer.js

Ignored files:
└─ .clasp.json

使い勝手の微妙なスクリプトエディタとはおさらば。お好みのエディタで快適に開発できます。

もちろんgit管理なども自由自在。
新しいMacでGitHubのSSH接続をするまでの環境構築手順 - Qiita

やったぜ。

Push

ローカルに落としてきたファイルは.jsファイルになっていますが、clasp pushすると.gsファイルとして、Web上のApp Scriptプロジェクトにアップロードされます。

$ clasp push

push対象のファイルはclasp statusで確認できます。

$ clasp status
Not ignored files:
└─ appsscript.json
└─ channel.js
└─ character.js
└─ main.js
└─ menu.js
└─ pr.js
└─ random.js
└─ reviewer.js

Ignored files:
└─ .DS_Store
└─ .clasp.json

git addのように変更ファイルだけをインデックス（ステージング）領域に上げる機能は無さそうです。pushするとカレントディレクトリ内のファイル構成で、一括アップロード&上書きされるので注意してください。

Pull

clasp pullでApp Scriptプロジェクト上のソースコードをダウンロードできます。

$ clasp pull

ローカルにある同一名ファイルは上書きされてしまうので、git管理しておくと良いでしょう。

Create

clasp createでローカルからGASプロジェクトの新規作成もできます。

$ clasp create sample_app
? Create which script? (Use arrow keys)
❯ standalone 
  docs 
  sheets 
  slides 
  forms 
  webapp 
  api

clasp 1.7.0から、standaloneだけでなく、Spreadsheetに紐付いたスクリプトやwebapp、apiなど、作成するプロジェクトのタイプが選べるようになったようです。

Created new standalone script: https://script.google.com/d/xxxxxxxxxx/edit
Warning: files in subfolder are not accounted for unless you set a '.claspignore' file.
Cloned 1 file.
└─ appsscript.json

clasp createで生成されるappsscript.json は、Apps Scriptプロジェクトのマニフェストファイルです。
Manifests | Apps Script | Google Developers

タイムゾーンやライブラリの設定などのプロパティがありますので、必要に応じて設定しましょう。

appsscript.json

{
  "timeZone": "America/New_York",
  "dependencies": {
  },
  "exceptionLogging": "STACKDRIVER",
  "runtimeVersion": "V8"
}

Manifest structure | Apps Script | Google Developers

Open

clasp openでスクリプトエディタにアクセスできます。コマンドを打つことでブラウザが開きます。

$ clasp open

スクリプトプロパティやトリガーをいじる際に使う。

Version

GASのバージョン管理もclaspでできます。

バージョン作成

clasp versionコマンドでバージョン作成が可能。引数でdescriptionをつけられます。

$ clasp version "Update sugoi kinou"
Created version 2.

手元で作業中はgit管理ベースでブランチ切ったりコミットしたりして、デプロイする際にclasp versionでバージョンインクリメントするような運用などが良さ気です。

バージョン履歴確認

clasp versionsコマンドではバージョン履歴が確認できます。

$ clasp versions
~ 3 Versions ~
3 - Update sugoku sugoi kinou
2 - Update sugoi kinou
1 - Update

claspで広がるGoogle Apps Scriptの世界

他にも様々なコマンドや機能があるので、公式リポジトリやドキュメントもご参照ください。
google/clasp: 🔗 Command Line Apps Script Projects
Command Line Interface using clasp - Apps Script | Google Developers

最近だとTypescriptで開発する人も多いみたいですね。
clasp が Typescript をサポートした！ - Qiita

自分はSpreadsheetと組み合わせてSlack bot作ったり、軽めのAPI作ったり程度しか経験ありませんが、極めればもっと色々なことができそうです

claspの導入でGoogle Apps Scriptのローカル開発＆git管理を実現する