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

build-tool / 導入ガイド

vite-plugin-google-apps-script

GAS-HTML環境特有の制約をビルド過程で回避

npm install -D vite-plugin-google-apps-script
このページの内容

vite-plugin-google-apps-script は、Google Apps Script (GAS) の HtmlService 上で動作するフロントエンドアプリケーションを Vite でビルドし、@google/clasp 等を用いて安全にデプロイするための Vite プラグインです。React や Vue などのモダンなフレームワークを GAS 用にシングルファイルバンドルする際、GAS 特有の制約やパースエラーの原因となるコード表現をビルドプロセス中で自動的に解決します。

概要と特徴

Vite と vite-plugin-singlefile を組み合わせて GAS 向けの HTML ファイルを生成する場合、標準のビルド設定のままでは GAS へのプッシュ時や実行時に改行コード、テンプレートリテラル内の URL、スクリプトレット記号のクォート問題などが発生することがあります。本プラグインはビルド時に3つの内部プラグインを適用し、これらの問題を透過的に解消します。

  • Terser によるコード圧縮の強制 (vite:enforce-terser): Vite 標準の esbuild ミニファイアがテンプレートリテラル内の改行を維持してしまう問題を回避するため、ビルド時のミニファイアを terser に切り替え、改行をエスケープシーケンス(\n)として安全に保持します。
  • テンプレートリテラル内の URL 除去 (vite:strip-urls-in-templates): GAS 環境へのデプロイ時に問題となりやすいテンプレートリテラル内の URL 文字列を、Babel AST 解析を用いてビルド変換時に自動除去または任意の文字列へ変換します。
  • 特定コードパターンの置換 (vite:replace-particular-expression): バンドル生成後の最終段階(enforce: 'post')において、JSDoc コメントの削除、GAS スクリプトレット(<? ... ?>, <?= ... ?>, <?!= ... ?>)を囲むダブルクォートのシングルクォート変換、およびカスタム置換ルールを実行します。

動作要件

  • Node.js: ESM / CommonJS 両対応の Node.js 環境
  • Vite: ビルドツール本体
  • 推奨併用パッケージ:
    • vite-plugin-singlefile(HTML への JS / CSS インライン化用)
    • @google/clasp(GAS プロジェクトへのデプロイ用)
    • @types/google-apps-script(TypeScript 開発時の型定義用)
  • ※ ミニファイアとして利用する terser および AST 変換に利用する @babel/parser, @babel/traverse, @babel/generator は本パッケージの dependencies に同梱されているため、個別の追加インストールは不要です。

インストール

関連パッケージとあわせて開発依存関係(devDependencies)としてインストールします。

.sh
# pnpm
pnpm add -D vite-plugin-google-apps-script vite vite-plugin-singlefile @google/clasp @types/google-apps-script

# npm
npm install -D vite-plugin-google-apps-script vite vite-plugin-singlefile @google/clasp @types/google-apps-script

# yarn
yarn add -D vite-plugin-google-apps-script vite vite-plugin-singlefile @google/clasp @types/google-apps-script

クイックスタート

1. Vite の設定

vite.config.ts で gas をインポートし、plugins 配列に追加します。vite-plugin-singlefile と併用する場合は、必ず viteSingleFile() より前に gas() を配置してください。

vite.config.ts
.ts
import { defineConfig } from 'vite';
import { gas } from 'vite-plugin-google-apps-script';
import { viteSingleFile } from 'vite-plugin-singlefile';

export default defineConfig({
  plugins: [gas(), viteSingleFile()],
  build: {
    outDir: 'dist',
  },
});

2. ビルドの実行

Vite のビルドを実行すると、GAS 環境向けに最適化された単一 HTML ファイルが dist/ に出力されます。

.sh
pnpm exec vite build

基本的な使い方

React / Vue 3 プロジェクトでの設定例

React や Vue 3 のプラグインと組み合わせる場合も、viteSingleFile() の直前に gas() を配置します。

vite.config.ts
.ts
// React の場合
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import { gas } from 'vite-plugin-google-apps-script';
import { viteSingleFile } from 'vite-plugin-singlefile';

export default defineConfig({
  plugins: [react(), gas(), viteSingleFile()],
  build: {
    outDir: 'dist',
  },
});
vite.config.ts
.ts
// Vue 3 の場合
import { defineConfig } from 'vite';
import vue from '@vitejs/plugin-vue';
import { gas } from 'vite-plugin-google-apps-script';
import { viteSingleFile } from 'vite-plugin-singlefile';

export default defineConfig({
  plugins: [vue(), gas(), viteSingleFile()],
  build: {
    outDir: 'dist',
  },
});

全オプションのカスタマイズ例

minify, url, replace の各オプションをカスタマイズする設定例です。

vite.config.ts
.ts
import { defineConfig } from 'vite';
import { gas } from 'vite-plugin-google-apps-script';
import { viteSingleFile } from 'vite-plugin-singlefile';

export default defineConfig({
  plugins: [
    gas({
      minify: {
        useTerserMinify: true,
      },
      url: {
        includes: [/\.([cm]?js|[cm]?ts|jsx|tsx)$/],
        excludes: [/node_modules/],
        urlPattern:
          /\b(?:https?:\/\/|ftp:\/\/|blob:|data:[^'")\s]+|\/\/)[\w/:%#$&?()~.=+\-{}]+/gi,
        parserPlugins: ['jsx', 'typescript'],
      },
      replace: {
        useDefault: true,
        replaceRules: [
          {
            from: 'https://test.example.com',
            to: '--masked-url--',
          },
          {
            from: /\/\*\*([\s\S]*?)\*\//g,
            replacer(_match, innerContent) {
              const singleLine = innerContent.replace(/\n/g, ' ');
              return `/**${singleLine}*/`;
            },
          },
        ],
      },
    }),
    viteSingleFile(),
  ],
  build: {
    outDir: 'dist',
  },
});

URL の除去をカスタム関数で制御する例

url.urlPattern に関数を渡すことで、テンプレートリテラル内の文字列に対して任意のサニタイズ処理を記述できます。

vite.config.ts
.ts
import { defineConfig } from 'vite';
import { gas } from 'vite-plugin-google-apps-script';
import { viteSingleFile } from 'vite-plugin-singlefile';

export default defineConfig({
  plugins: [
    gas({
      url: {
        urlPattern: (input) =>
          input.replace(/https:\/\/internal\.example\.com/g, ''),
      },
    }),
    viteSingleFile(),
  ],
});

デフォルト置換ルールを無効化する例

プリセットの置換ルールを無効化し、独自ルールのみを適用する場合は useDefault: false と replaceRules をあわせて指定します。

vite.config.ts
.ts
import { defineConfig } from 'vite';
import { gas } from 'vite-plugin-google-apps-script';
import { viteSingleFile } from 'vite-plugin-singlefile';

export default defineConfig({
  plugins: [
    gas({
      replace: {
        useDefault: false,
        replaceRules: [
          {
            from: /"(<\?!{0,1}={0,1}.+?\?>)"/g,
            to: "'$1'",
          },
        ],
      },
    }),
    viteSingleFile(),
  ],
});

API リファレンス

gas(options?)

ビルド専用の Vite プラグイン配列(PluginOption)を返します。すべての内部プラグインは apply: 'build' が設定されており、開発サーバー(vite dev)の動作には影響しません。

index.d.ts
.ts
import type { PluginOption } from 'vite';
import type { ParserPlugin } from '@babel/parser';

export type Options = {
  minify?: EnforceTerserOptions;
  url?: StripUrlsOptions;
  replace?: ReplaceParticularExpressionOptions;
};

export type EnforceTerserOptions = {
  useTerserMinify?: boolean;
};

export type StripUrlsOptions = {
  includes?: Array<string | RegExp> | string | RegExp;
  excludes?: Array<string | RegExp> | string | RegExp;
  urlPattern?: RegExp | ((s: string) => string);
  parserPlugins?: ParserPlugin[];
};

export type ReplaceRule =
  | {
      from: string | RegExp;
      to?: string;
      replacer?: (substring: string, ...args: string[]) => string;
    }
  | {
      from: string | RegExp;
      to: string;
      replacer?: never;
    }
  | {
      from: string | RegExp;
      to?: never;
      replacer: (substring: string, ...args: string[]) => string;
    };

export type ReplaceParticularExpressionOptions =
  | {
      replaceRules?: Array<ReplaceRule>;
      useDefault?: true;
    }
  | {
      replaceRules: Array<ReplaceRule>;
      useDefault: false;
    };

export declare const gas: (options?: Options) => PluginOption;

options.minify (EnforceTerserOptions)

Vite の build.minify 設定を制御するオプションです(内部プラグイン名: vite:enforce-terser)。

プロパティ / 引数 型 デフォルト 説明
useTerserMinify boolean true true の場合は build.minify を 'terser' に設定します。false の場合は build.minify を false に設定し、コード圧縮を無効化します。

options.url (StripUrlsOptions)

テンプレートリテラル内の URL を検出・除去する変換処理を制御するオプションです(内部プラグイン名: vite:strip-urls-in-templates)。

プロパティ / 引数 型 デフォルト 説明
includes Array<string | RegExp> | string | RegExp [/\.([cm]?js|[cm]?ts|jsx|tsx)$/] 変換対象とするファイルパスのパターン。Vite の createFilter に渡されます。
excludes Array<string | RegExp> | string | RegExp undefined 変換対象から除外するファイルパスのパターン。Vite の createFilter に渡されます。
urlPattern RegExp | ((s: string) => string) /\b(?:https?:\/\/|ftp:\/\/|blob:|data:[^'")\s]+|\/\/)[\w/:%#$&?()~.=+\-{}]+/gi URL を検出する正規表現、または文字列を受け取り変換後の文字列を返すカスタム関数。正規表現を指定した場合は一致箇所が空文字列 '' に置換されます。
parserPlugins ParserPlugin[] ['jsx', 'typescript'] @babel/parser の parse 関数に渡す構文解析プラグインの配列。

options.replace (ReplaceParticularExpressionOptions)

バンドル生成時(generateBundle フック、enforce: 'post')にチャンクコードに対して文字列または正規表現による置換を実行するオプションです(内部プラグイン名: vite:replace-particular-expression)。

プロパティ / 引数 型 デフォルト 説明
useDefault boolean true デフォルトの置換ルール(JSDoc コメント削除、スクリプトレットのクォート変換)を適用するかどうかを指定します。false を指定する場合は replaceRules の指定が必須となります。
replaceRules Array<ReplaceRule> [] カスタム置換ルールの配列。各ルールには検索対象の from(文字列または正規表現)と、置換後の文字列 to または置換関数 replacer のいずれかを指定します。

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

Terser ミニファイアの強制 (vite:enforce-terser)

Vite の設定で build.minify: 'esbuild' が明示的に指定されていた場合でも、本プラグインは警告を出力した上で useTerserMinify の設定に従い 'terser' または false に上書きします。これにより、テンプレートリテラル内の改行コードがそのまま残ることによる GAS 側のランタイム・デプロイエラーを防ぎます。

AST 解析による URL 除去 (vite:strip-urls-in-templates)

  • @babel/parser で対象ファイルを AST にパースし、TemplateLiteral ノード(`...`)の固定文字列部分(quasis)と、そのテンプレートリテラルの内側(${...} 内など)に存在する StringLiteral ノードのみを走査・変換します。
  • 通常のダブルクォートやシングルクォートで記述された、テンプレートリテラル外の文字列リテラル(const url = 'https://example.com' や JSX 属性 href="https://example.com" など)は変更されません。
  • ファイルのパースに失敗した場合や、該当する URL が存在せず AST の変更が発生しなかった場合は変換をスキップします。

デフォルトの置換ルール (vite:replace-particular-expression)

replace.useDefault が false でない場合、カスタムの replaceRules が順次実行された後に以下のプリセットルールが適用されます。

対象 検索パターン (from) 置換内容 (to) 目的
JSDoc コメント /\n*\/\*\*[\n\s\S]*?\*\/\n*/g ''(空文字列) バンドル内に残った JSDoc コメントおよび前後の改行を除去します。
GAS スクリプトレット /"(<\?!{0,1}={0,1}.+?\?>)"/g "'$1'" "<?!= value ?>" や "<?= value ?>" のようにダブルクォートで囲まれたスクリプトレットを '<?!= value ?>' のようにシングルクォートへ変換します。

実践レシピ・連携例

@google/clasp と組み合わせた GAS デプロイ構成

フロントエンド(Vite)と GAS サーバーサイドスクリプトを組み合わせ、@google/clasp で dist ディレクトリをデプロイする構成例です。

server/index.ts
.ts
// 1. サーバーサイドのエントリーポイント: dist/index.html を HtmlService で配信
export function doGet() {
  return HtmlService.createTemplateFromFile('index').evaluate();
}

export function getMessage(name: string) {
  return `Hello, ${name}!`;
}
src/main.ts
.ts
// 2. フロントエンドからの呼び出し (google.script.run)
declare global {
  const google: any;
}

google.script.run
  .withSuccessHandler((message: string) => {
    console.log(message);
  })
  .getMessage('User');
.clasp.json
.json
{
  "scriptId": "YOUR_SCRIPT_ID",
  "rootDir": "./dist"
}

制限事項と注意点

  • プラグインの記述順序: vite-plugin-singlefile を使用する際は、HTML へ JS バンドルがインライン化される前にチャンク変換や置換処理を完了させる必要があるため、必ず plugins: [gas(), viteSingleFile()] の順で指定してください。
  • replaceRules における正規表現の扱い: replace オプションの from に正規表現を指定する場合、内部で RegExp.prototype.test() による一致判定を行った後に String.prototype.replace() を実行します。すべての出現箇所を置換したい場合は正規表現に g フラグを付与してください。
  • to と replacer の優先順位: ReplaceRule で to と replacer の両方が渡された場合は replacer が優先されます(TypeScript の型定義上は排他指定となります)。

ライセンス

MIT License