clasp（GAS CLI）が便利すぎる！Google Apps Script開発を10倍効率化する使い方とベストプラクティス

# Node.jsのバージョン確認
node --version
npm --version

# Node.jsがインストールされていない場合
# 公式サイト (https://nodejs.org/) からダウンロード
# または、Node Version Manager (nvm) を使用

# nvmを使用する場合 (推奨)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install --lts
nvm use --lts

# claspをグローバルインストール
npm install -g @google/clasp

# インストール確認
clasp --version

# Googleアカウントでログイン
clasp login

# ログイン状況確認
clasp auth --status

# 既存プロジェクトのクローン
# まず、GASエディタでプロジェクトIDを確認
# URL: https://script.google.com/d/{PROJECT_ID}/edit

# プロジェクト用ディレクトリ作成
mkdir my-gas-project
cd my-gas-project

# 既存プロジェクトをクローン
clasp clone "PROJECT_ID"

# ファイル一覧確認
ls -la

# 新規プロジェクト作成
mkdir new-gas-project
cd new-gas-project

# 新規プロジェクト初期化
clasp create

# プロジェクトタイプを選択
# 1. standalone - スタンドアロンスクリプト
# 2. sheets - Google Sheets連携
# 3. docs - Google Docs連携
# 4. forms - Google Forms連携
# 5. slides - Google Slides連携
# 6. webapp - Webアプリケーション

# 作成されたファイルを確認
ls -la
cat appsscript.json

// Code.js - テスト用の簡単な関数を作成
function testFunction() {
  console.log('Hello from local development!');
  
  // スプレッドシートの操作例
  const sheet = SpreadsheetApp.getActiveSheet();
  sheet.getRange('A1').setValue('clasp test');
  
  return 'Success!';
}

# ローカルの変更をGASにプッシュ
clasp push

# 成功すると以下のようなメッセージが表示される
# └─ Code.js
# Pushed 1 file.

# GAS側の変更をローカルにプル
clasp pull

# GASエディタで関数を実行してテスト
# または、コマンドラインから実行
clasp run testFunction

// .vscode/extensions.json - 推奨拡張機能リスト
{
  "recommendations": [
    "google.apps-script",
    "ms-vscode.vscode-typescript-next",
    "esbenp.prettier-vscode",
    "bradlc.vscode-tailwindcss",
    "ms-vscode.vscode-json",
    "formulahendry.auto-rename-tag",
    "christian-kohler.path-intellisense"
  ]
}

// .vscode/settings.json - GAS開発用設定
{
  "typescript.preferences.includePackageJsonAutoImports": "auto",
  "typescript.suggest.autoImports": true,
  "editor.formatOnSave": true,
  "editor.codeActionsOnSave": {
    "source.fixAll": true
  },
  "files.associations": {
    "*.gs": "javascript"
  },
  "emmet.includeLanguages": {
    "javascript": "javascriptreact"
  }
}

# プロジェクトをTypeScript対応にする
npm init -y

# TypeScriptとGAS型定義をインストール
npm install -D typescript @types/google-apps-script

# TypeScript設定ファイル作成
npx tsc --init

// tsconfig.json - GAS用TypeScript設定
{
  "compilerOptions": {
    "target": "ES2019",
    "module": "ESNext",
    "lib": ["ES2019"],
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "moduleResolution": "node",
    "declaration": true,
    "declarationMap": true,
    "sourceMap": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}

// src/main.ts - TypeScriptでの型安全なGASコード
interface UserData {
  name: string;
  email: string;
  department: string;
}

class SpreadsheetManager {
  private sheet: GoogleAppsScript.Spreadsheet.Sheet;

  constructor(sheetName: string) {
    const spreadsheet = SpreadsheetApp.getActiveSpreadsheet();
    this.sheet = spreadsheet.getSheetByName(sheetName) || 
                 spreadsheet.insertSheet(sheetName);
  }

  addUser(userData: UserData): void {
    const lastRow = this.sheet.getLastRow();
    const range = this.sheet.getRange(lastRow + 1, 1, 1, 3);
    
    range.setValues([[
      userData.name,
      userData.email,
      userData.department
    ]]);
  }

  getAllUsers(): UserData[] {
    const range = this.sheet.getDataRange();
    const values = range.getValues();
    
    return values.slice(1).map(row => ({
      name: row[0] as string,
      email: row[1] as string,
      department: row[2] as string
    }));
  }
}

// グローバル関数（GASから呼び出し可能）
function addNewUser(): void {
  const manager = new SpreadsheetManager('Users');
  
  manager.addUser({
    name: 'John Doe',
    email: 'john@example.com',
    department: 'Engineering'
  });
}

// .vscode/launch.json - デバッグ設定
{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "GAS Debug",
      "type": "node",
      "request": "launch",
      "program": "${workspaceFolder}/src/main.ts",
      "outFiles": ["${workspaceFolder}/dist/**/*.js"],
      "console": "integratedTerminal",
      "env": {
        "NODE_ENV": "development"
      }
    }
  ]
}

my-gas-project/
├── .vscode/
│   ├── settings.json
│   ├── launch.json
│   └── extensions.json
├── src/
│   ├── main.ts                 # メイン処理
│   ├── utils/
│   │   ├── spreadsheet.ts      # スプレッドシート操作
│   │   ├── gmail.ts           # Gmail操作
│   │   └── calendar.ts        # カレンダー操作
│   ├── types/
│   │   └── index.ts           # 型定義
│   └── config/
│       └── settings.ts        # 設定値
├── tests/
│   └── main.test.ts           # テストファイル
├── dist/                      # コンパイル後のファイル
├── package.json
├── tsconfig.json
├── .clasp.json               # clasp設定
├── .claspignore              # 除外ファイル
├── .gitignore
└── README.md

# .gitignore - Gitで管理しないファイル
# 依存関係
node_modules/
npm-debug.log*

# コンパイル結果
dist/
*.js
*.js.map

# IDE設定
.vscode/settings.json

# OS固有ファイル
.DS_Store
Thumbs.db

# 環境固有設定
.env
.env.local

# clasp認証情報
.clasprc.json

# .claspignore - GASにプッシュしないファイル
# ソースファイル（TypeScript）
src/
tests/

# 設定ファイル
tsconfig.json
package.json
package-lock.json
.gitignore
.claspignore
README.md

# 開発ツール設定
.vscode/
.eslintrc.js
.prettierrc

# Node.js関連
node_modules/

# 基本的なブランチ戦略
git checkout -b develop                    # 開発ブランチ
git checkout -b feature/add-user-management # 機能開発ブランチ

# 開発作業
# ... コード編集 ...

# TypeScriptコンパイル
npm run build

# ローカルテスト
npm test

# コミット
git add .
git commit -m "feat: ユーザー管理機能を追加"

# 開発ブランチにマージ
git checkout develop
git merge feature/add-user-management

# GASにデプロイ（develop環境）
clasp push

# 本番リリース時
git checkout main
git merge develop
clasp push  # 本番環境にデプロイ

# .github/workflows/gas-deploy.yml - GitHub Actions設定
name: GAS Deploy

on:
  push:
    branches: [ main, develop ]
  pull_request:
    branches: [ main ]

jobs:
  test:
    runs-on: ubuntu-latest
    
    steps:
    - uses: actions/checkout@v3
    
    - name: Setup Node.js
      uses: actions/setup-node@v3
      with:
        node-version: '18'
        cache: 'npm'
        
    - name: Install dependencies
      run: npm ci
      
    - name: Run tests
      run: npm test
      
    - name: Build TypeScript
      run: npm run build
      
    - name: Lint check
      run: npm run lint

  deploy:
    needs: test
    runs-on: ubuntu-latest
    if: github.ref == 'refs/heads/main'
    
    steps:
    - uses: actions/checkout@v3
    
    - name: Setup Node.js
      uses: actions/setup-node@v3
      with:
        node-version: '18'
        cache: 'npm'
        
    - name: Install dependencies
      run: npm ci
      
    - name: Build
      run: npm run build
      
    - name: Setup clasp
      run: |
        npm install -g @google/clasp
        echo "$CLASP_CREDENTIALS" > ~/.clasprc.json
      env:
        CLASP_CREDENTIALS: ${{ secrets.CLASP_CREDENTIALS }}
        
    - name: Deploy to GAS
      run: clasp push

// package.json - 必要なスクリプトを追加
{
  "name": "my-gas-project",
  "version": "1.0.0",
  "scripts": {
    "build": "tsc",
    "watch": "tsc --watch",
    "test": "jest",
    "test:watch": "jest --watch",
    "lint": "eslint src/**/*.ts",
    "lint:fix": "eslint src/**/*.ts --fix",
    "deploy:dev": "npm run build && clasp push",
    "deploy:prod": "npm run build && clasp push --deploymentId YOUR_DEPLOYMENT_ID"
  },
  "devDependencies": {
    "@types/google-apps-script": "^1.0.0",
    "@types/jest": "^29.0.0",
    "eslint": "^8.0.0",
    "jest": "^29.0.0",
    "typescript": "^5.0.0"
  }
}

// tests/spreadsheet.test.ts - テストファイル例
import { SpreadsheetManager } from '../src/utils/spreadsheet';

// GAS APIのモック
jest.mock('SpreadsheetApp', () => ({
  getActiveSpreadsheet: jest.fn(() => ({
    getSheetByName: jest.fn(),
    insertSheet: jest.fn()
  }))
}));

describe('SpreadsheetManager', () => {
  let manager: SpreadsheetManager;
  
  beforeEach(() => {
    manager = new SpreadsheetManager('TestSheet');
  });
  
  test('ユーザーデータの追加が正常に動作する', () => {
    const userData = {
      name: 'Test User',
      email: 'test@example.com',
      department: 'Test Department'
    };
    
    // テスト実行
    expect(() => {
      manager.addUser(userData);
    }).not.toThrow();
  });
  
  test('無効なデータでエラーが発生する', () => {
    const invalidData = {
      name: '',
      email: 'invalid-email',
      department: ''
    };
    
    expect(() => {
      manager.addUser(invalidData);
    }).toThrow();
  });
});

# 複数環境の設定
# 開発環境
clasp create --title "MyProject-Dev" --type standalone
# .clasp.json を .clasp.dev.json としてバックアップ

# ステージング環境  
clasp create --title "MyProject-Staging" --type standalone
# .clasp.json を .clasp.staging.json としてバックアップ

# 本番環境
clasp create --title "MyProject-Prod" --type standalone
# .clasp.json を .clasp.prod.json としてバックアップ

# 環境切り替えスクリプト
#!/bin/bash
# deploy.sh

ENVIRONMENT=$1

if [ "$ENVIRONMENT" = "dev" ]; then
    cp .clasp.dev.json .clasp.json
elif [ "$ENVIRONMENT" = "staging" ]; then
    cp .clasp.staging.json .clasp.json
elif [ "$ENVIRONMENT" = "prod" ]; then
    cp .clasp.prod.json .clasp.json
else
    echo "使用法: ./deploy.sh [dev|staging|prod]"
    exit 1
fi

echo "環境: $ENVIRONMENT"
npm run build
clasp push

# 認証エラーの診断と解決

# 1. 現在の認証状況確認
clasp auth --status

# 2. 認証エラーが発生した場合の対処
# 既存の認証情報をクリア
clasp logout

# 再ログイン
clasp login

# 3. Apps Script APIが有効になっているか確認
# https://script.google.com/home/usersettings で
# 「Google Apps Script API」を有効にする

# 4. 複数アカウントの問題
# 特定のアカウントでログイン
clasp login --localhost

# 5. 認証ファイルの場所確認（トラブル時）
ls -la ~/.clasprc.json

# よくあるプッシュエラーと対処法

# エラー1: "Manifest file has been updated"
# 解決: ローカルのappsscript.jsonを更新
clasp pull --only-appscript

# エラー2: "File too large"
# 解決: .claspignoreで不要ファイルを除外
echo "node_modules/" >> .claspignore
echo "tests/" >> .claspignore

# エラー3: "Invalid project ID"
# 解決: .clasp.jsonの設定確認
cat .clasp.json
# 正しいscriptIdが設定されているか確認

# エラー4: "Permission denied"
# 解決: プロジェクトの共有権限確認
# GASエディタで共有設定を確認

# 強制的にローカルの状態でオーバーライト
clasp push --force

# ファイル同期のトラブルシューティング

# 1. 現在の同期状況確認
clasp status

# 2. 同期の不整合が発生した場合
# GAS側の最新状態を取得
clasp pull

# ローカルの変更をバックアップ
cp -r src src_backup

# 強制的にGASの状態に合わせる
clasp pull --force

# 3. 特定のファイルのみ同期
# 特定ファイルのみプッシュ
clasp push --only "Code.js"

# 4. TypeScriptの場合のトラブル
# コンパイルされたJSファイルが正しく生成されているか確認
npm run build
ls -la dist/

# 5. ファイル名の問題（日本語、特殊文字）
# ASCII文字のみの名前に変更することを推奨