@gasboost/vite 0.1.0 → 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 gasboost
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,8 +1,11 @@
 # @gasboost/vite
 
-`@gasboost/app` で構築したアプリケーションを Google Apps Script 向けにビルドするための Vite プラグインです。
+`@gasboost/app` で構築した Google Apps Script アプリケーションを、Vite でビルド・ローカル開発するためのプラグインです。
 
-アプリケーションの entry file を静的解析し、`AppsScript` に登録されたハンドラを検出して、Google Apps Script が認識するためのグローバル関数宣言を生成します。
+`@gasboost/vite` は用途ごとに2つの Vite Plugin を提供します。
+
+- `build` — Google Apps Script 向けの production build
+- `dev` — ローカル開発時の RPC 実行
 
 ## インストール
 
@@ -18,119 +21,175 @@ npm install @gasboost/app
 npm install -D @gasboost/vite vite
 ```
 
-## 使い方
+## Quick Start
 
-まず通常の Gasboost アプリケーションを作成します。
+まず `@gasboost/app` でバックエンドを定義します。
 
 ```ts
-// src/main.ts
+// src/server.ts
 
 import { AppsScript } from "@gasboost/app";
 
 const app = new AppsScript()
-  .get((request) => {
+  .get(() => {
     return HtmlService.createHtmlOutput("Hello");
   })
   .post((request) => {
     return ContentService.createTextOutput(request.text());
   })
-  .call("sum", (a: number, b: number) => a + b);
+  .call("sum", (a: number, b: number) => a + b)
+  .call("getUser", async (id: string) => ({
+    id,
+    name: "Taro",
+  }));
 
 export default app;
 ```
 
-Vite を設定します。
+`gasboost()` から `build` と `dev` を取得し、1つの `vite.config.ts` の中で mode に応じて使い分けます。
+
+frontend と backend は成果物と build graph が異なるため、同時に1つの Vite build へ混在させません。
 
 ```ts
 // vite.config.ts
 
+import react from "@vitejs/plugin-react";
 import { defineConfig } from "vite";
+import { viteSingleFile } from "vite-plugin-singlefile";
 import { gasboost } from "@gasboost/vite";
 
-export default defineConfig({
-  plugins: [
-    gasboost({
-      entry: "src/main.ts",
-    }),
-  ],
+const { build, dev } = gasboost({
+  entry: "src/server.ts",
+  envDir: ".env",
 });
-```
 
-通常通りビルドできます。
+export default defineConfig(({ mode }) => {
+  if (mode === "server") {
+    return {
+      plugins: [build],
+      build: {
+        outDir: "dist",
+        emptyOutDir: false,
+      },
+    };
+  }
+
+  return {
+    plugins: [react(), viteSingleFile(), dev],
+    build: {
+      outDir: "dist",
+    },
+  };
+});
+```
 
-```bash
-vite build
+この例では、frontend build と backend build を mode で分離します。
+
+```json
+{
+  "scripts": {
+    "dev": "vite",
+    "build:client": "vite build --mode client",
+    "build:server": "vite build --mode server",
+    "build": "pnpm build:client && pnpm build:server"
+  }
+}
 ```
 
-## オプション
+```text
+vite
+  ↓
+gasboost:dev
 
-### `entry`
+vite build --mode client
+  ↓
+frontend build
 
-必須です。
+vite build --mode server
+  ↓
+gasboost:build
+```
+
+frontend 側の React、single-file 化などの設定は利用側プロジェクトの責務です。
 
-`AppsScript` アプリケーションを定義している entry file のパスを指定します。
+## gasboost()
 
 ```ts
-gasboost({
-  entry: "src/main.ts",
+const { build, dev } = gasboost({
+  entry: "src/server.ts",
+  envDir: "config",
 });
 ```
 
-entry file には1つの `AppsScript` インスタンスを定義し、そのインスタンスを default export する必要があります。
+戻り値:
 
 ```ts
-const app = new AppsScript();
-
-export default app;
+{
+  build: Plugin;
+  dev: Plugin;
+}
 ```
 
-チェーン形式の登録に対応しています。
-
-```ts
-const app = new AppsScript()
-  .get(...)
-  .post(...)
-  .call("getUser", ...);
+### `entry`
 
-export default app;
-```
+必須です。
 
-インスタンス生成後に登録する形式にも対応しています。
+`AppsScript` を定義して default export している entry file を指定します。
 
 ```ts
-const app = new AppsScript();
-
-app.get(...);
-app.call("getUser", ...);
-
-export default app;
+gasboost({
+  entry: "src/server.ts",
+});
 ```
 
 ### `envDir`
 
 任意です。
 
-Vite が環境変数ファイルを読み込むディレクトリを指定します。
+build 時に Vite が環境変数ファイルを読み込むディレクトリを指定します。
 
 ```ts
 gasboost({
-  entry: "src/main.ts",
+  entry: "src/server.ts",
   envDir: "config",
 });
 ```
 
-例えば以下の構成を利用できます。
+---
 
-```text
-config/
-├── .env
-├── .env.development
-└── .env.production
+# Build Plugin
+
+`build` は `vite build` のときだけ動作し、GAS backend build を担当します。
+
+frontend / backend を同じ `vite.config.ts` で扱う場合は、server 用 mode のときだけ `plugins` に含めてください。
+
+```ts
+const { build } = gasboost({
+  entry: "src/server.ts",
+});
+
+export default defineConfig(({ mode }) => {
+  if (mode === "server") {
+    return {
+      plugins: [build],
+    };
+  }
+
+  return {
+    plugins: [],
+  };
+});
 ```
 
-## 生成されるグローバル関数
+`build` plugin は次の処理を担当します。
 
-Google Apps Script はトップレベルのグローバル関数を entry point として認識します。
+- entry file の静的解析
+- `AppsScript` に登録された GET / POST / RPC の検出
+- GAS が認識するグローバル関数宣言の生成
+- GAS 向け Vite build configuration
+- 環境変数の読み込み
+
+## グローバル関数の生成
 
 例えば次のアプリケーションを定義した場合:
 
@@ -144,7 +203,7 @@ const app = new AppsScript()
 export default app;
 ```
 
-ビルド結果には以下に対応するグローバル関数宣言が生成されます。
+build plugin は GAS が認識するためのグローバル関数宣言を生成します。
 
 ```js
 function doGet() {}
@@ -153,56 +212,51 @@ function getUser() {}
 function sum() {}
 ```
 
-これらの宣言は Google Apps Script に関数名を認識させるためのものです。
-
-実際の dispatch 処理は行いません。
-
-ハンドラの実体は `@gasboost/app` がランタイム上で登録します。
+これらは関数名を Google Apps Script に認識させるための宣言です。
 
-責務は次のように分離されています。
+実際のハンドラ登録と dispatch は `@gasboost/app` がランタイム上で行います。
 
 ```text
-@gasboost/app
-  runtime registration
-  handler dispatch
-  globalThis implementation
-
 @gasboost/vite
   static analysis
-  GAS build configuration
   global function declarations
+        ↓
+@gasboost/app
+  runtime registration
+  dispatch
 ```
 
 ## 静的解析
 
-プラグインは指定された entry file を静的解析します。
-
-対象となる `AppsScript` インスタンスに対する登録を検出します。
+entry file には1つの `AppsScript` インスタンスを定義し、default export します。
 
 ```ts
+const app = new AppsScript();
+
 app.get(...);
-app.post(...);
 app.call("getUser", ...);
+
+export default app;
 ```
 
-別オブジェクトの同名メソッドは無視されます。
+チェーン形式にも対応しています。
 
 ```ts
-other.get(...);
-other.call("something", ...);
-```
+const app = new AppsScript()
+  .get(...)
+  .post(...)
+  .call("getUser", ...);
 
-### RPC 名
+export default app;
+```
 
 RPC 名は文字列リテラルで指定する必要があります。
 
-対応:
-
 ```ts
 app.call("getUser", handler);
 ```
 
-非対応:
+次のような動的な名前は静的解析の対象外です。
 
 ```ts
 const name = "getUser";
@@ -210,123 +264,390 @@ const name = "getUser";
 app.call(name, handler);
 ```
 
-ビルド時に生成する GAS グローバル関数名を静的に確定するため、この制約があります。
+build 時に GAS のグローバル関数名を確定する必要があるためです。
 
-### 重複登録
+## 検証
 
-以下の曖昧な登録はエラーになります。
+静的解析時には、曖昧なアプリケーション定義をエラーとして扱います。
 
 - GET ハンドラの重複
 - POST ハンドラの重複
 - RPC 名の重複
-- entry 内に複数の `AppsScript` インスタンスが存在する場合
-
-`AppsScript` インスタンスは default export されている必要があります。
-
-## GAS 向けビルド設定
+- entry 内の複数 `AppsScript` インスタンス
+- default export されていない `AppsScript`
 
-`gasboost()` が Google Apps Script 向けの Vite build configuration を提供します。
+## GAS 向け build configuration
 
-現在は以下の設定を利用します。
+現在の build 設定:
 
 - target: ECMAScript 2019
 - output format: CommonJS
 - output directory: `dist`
-- `entry` で指定されたファイルを build input として利用
-
-利用側の Vite config で GAS 固有の build setting を重複して定義する必要はありません。
+- `entry` を build input として利用
 
 ## 環境変数
 
-環境変数は Vite 標準の仕組みを利用します。
-
-例えば:
+Vite 標準の環境変数機構を利用します。
 
 ```text
-config/.env
-```
-
-```env
-VITE_API_URL=https://example.com
+config/
+├── .env
+├── .env.development
+└── .env.production
 ```
 
-`envDir` を設定します。
-
 ```ts
-gasboost({
-  entry: "src/main.ts",
+const { build } = gasboost({
+  entry: "src/server.ts",
   envDir: "config",
 });
 ```
 
-アプリケーションから通常通り参照できます。
+アプリケーションでは通常の Vite と同様に参照できます。
 
 ```ts
 const apiUrl = import.meta.env.VITE_API_URL;
 ```
 
-mode ごとの環境変数ファイルにも対応します。
+---
 
-```bash
-vite build --mode production
+# Dev Plugin
+
+`dev` は Vite Dev Server 上でのみ動作します。
+
+frontend の開発用 Vite config に追加して利用します。
+
+```ts
+const { dev } = gasboost({
+  entry: "src/server.ts",
+});
+
+export default defineConfig({
+  plugins: [dev],
+});
 ```
 
-`envDir: "config"` の場合、例えば以下が読み込まれます。
+`dev` plugin は、GAS にデプロイしなくてもローカル環境から `AppsScript` の RPC を実行できるエンドポイントを Vite Dev Server に追加します。
+
+## Local RPC
+
+ローカル RPC のエンドポイントは次の形式です。
 
 ```text
-config/.env.production
+POST /__gasboost/{rpcName}
+```
+
+例えば、
+
+```ts
+const app = new AppsScript().call("sum", (a: number, b: number) => a + b);
+
+export default app;
+```
+
+に対して、
+
+```http
+POST /__gasboost/sum
+Content-Type: application/json
+```
+
+```json
+{
+  "args": [1, 2]
+}
 ```
 
-## 責務
+を送信すると、内部では次の dispatch が実行されます。
+
+```ts
+app.dispatch("sum", 1, 2);
+```
+
+レスポンス:
+
+```json
+3
+```
 
-`@gasboost/vite` はビルド時の処理のみを担当します。
+## RPC Request
 
-主な責務:
+Request Body は次の形式です。
 
-- `AppsScript` 登録内容の静的解析
-- Google Apps Script 向け Vite configuration
-- GAS グローバル関数宣言の生成
-- Vite 環境変数との統合
+```ts
+{
+  args: unknown[];
+}
+```
+
+例えば複数の引数を持つ RPC:
+
+```ts
+app.call(
+  "example",
+  (id: number, name: string, active: boolean, options: { value: number }) => {
+    // ...
+  },
+);
+```
 
-以下は担当しません。
+に対して、
+
+```json
+{
+  "args": [
+    1,
+    "Taro",
+    true,
+    {
+      "value": 4
+    }
+  ]
+}
+```
 
-- GET ハンドラの実行
-- POST ハンドラの実行
-- RPC dispatch
-- ハンドラ実体のランタイム登録
-- Google Apps Script API 自体の抽象化
+のように送信できます。
 
-これらの runtime responsibility は `@gasboost/app` が担当します。
+### 引数なし RPC
 
-## 現在の制約
+Request Body が空の場合は、引数なし RPC として扱われます。
 
-Analyzer は、意図的にシンプルな entry file 構造のみを対象としています。
+```http
+POST /__gasboost/noArgs
+```
 
-以下のような alias を介した default export は現在対象外です。
+内部では次のように dispatch されます。
 
 ```ts
-const app = new AppsScript();
-const exported = app;
+app.dispatch("noArgs");
+```
 
-export default exported;
+明示的に送る場合は次でも構いません。
+
+```json
+{
+  "args": []
+}
 ```
 
-別関数の内部に登録処理を隠す形式も対象外です。
+## RPC Response
+
+`@gasboost/app` の `dispatch()` が返す `AppsScriptResponse.contents` を、そのまま HTTP Response Body として返します。
+
+例えば、
 
 ```ts
-registerHandlers(app);
+app.call("getUser", () => ({
+  id: 1,
+  name: "Taro",
+}));
+```
+
+に対するレスポンスは:
+
+```json
+{
+  "id": 1,
+  "name": "Taro"
+}
+```
+
+となります。
+
+Response の Content-Type は:
+
+```text
+application/json; charset=utf-8
+```
+
+です。
+
+## Async RPC
+
+非同期 RPC にも対応しています。
+
+```ts
+app.call("loadUser", async (id: string) => {
+  const user = await loadUser(id);
+
+  return user;
+});
+```
+
+dev plugin は `dispatch()` の完了を待ってからレスポンスを返します。
+
+## 開発中の module loading
+
+RPC リクエストごとに、指定された `entry` を Vite の `ssrLoadModule()` で読み込みます。
+
+```text
+POST /__gasboost/sum
+        ↓
+ssrLoadModule("src/server.ts")
+        ↓
+AppsScript.dispatch("sum", ...)
+```
+
+そのため、Vite Dev Server 上の最新のサーバーコードを利用して RPC を実行できます。
+
+## Error Response
+
+### 不正な Request Body
+
+JSON として不正な body や、`args` が配列でない body は `400` を返します。
+
+```json
+{
+  "args": "invalid"
+}
+```
+
+レスポンス例:
+
+```json
+{
+  "error": {
+    "name": "InvalidRpcRequestError",
+    "message": "Invalid RPC request body. Expected { args: unknown[] }."
+  }
+}
 ```
 
-別ファイルに登録処理を分散する形式も現在対象外です。
+JSON 自体が不正な場合も `400` です。
+
+### POST 以外
+
+Local RPC endpoint は POST のみ受け付けます。
+
+```http
+GET /__gasboost/sum
+```
+
+は `405` になります。
+
+```json
+{
+  "error": {
+    "name": "MethodNotAllowedError",
+    "message": "Only POST is allowed."
+  }
+}
+```
+
+### 未登録 RPC
+
+存在しない RPC を呼び出した場合は `500` を返します。
+
+```text
+POST /__gasboost/unknown
+```
+
+```json
+{
+  "error": {
+    "name": "Error",
+    "message": "Function unknown is not registered."
+  }
+}
+```
+
+### Handler Error
+
+RPC handler 内で例外が発生した場合も `500` として JSON で返されます。
+
+```json
+{
+  "error": {
+    "name": "TypeError",
+    "message": "handler failed"
+  }
+}
+```
+
+## Local RPC の対象 path
+
+次の形式だけを RPC として扱います。
+
+```text
+/__gasboost/{rpcName}
+```
+
+例えば以下は対象です。
+
+```text
+/__gasboost/getUser
+/__gasboost/sum
+```
+
+一方、次のような path は RPC として扱いません。
+
+```text
+/__gasboost/
+/__gasboost/foo/bar
+/api/users
+```
+
+通常の Vite middleware chain に処理を渡します。
+
+query string が付いていても RPC 名は正しく解決されます。
+
+```text
+/__gasboost/hello?foo=bar
+```
+
+URL encoded な RPC 名も decode されます。
+
+```text
+/__gasboost/hello%20world
+```
+
+---
+
+# build と dev の責務
+
+```text
+gasboost()
+   │
+   ├─ build
+   │    ├─ AppsScript の静的解析
+   │    ├─ GAS グローバル関数生成
+   │    ├─ GAS 向け build config
+   │    └─ backend production build
+   │
+   └─ dev
+        ├─ Vite Dev Server middleware
+        ├─ Local RPC endpoint
+        ├─ entry の ssrLoadModule
+        └─ AppsScript.dispatch
+```
+
+frontend と backend を1つの `vite.config.ts` で扱う場合は、mode で分岐します。
 
 ```ts
-import { registerHandlers } from "./handlers";
+const { build, dev } = gasboost({
+  entry: "src/server.ts",
+});
+
+export default defineConfig(({ mode }) => {
+  if (mode === "server") {
+    return {
+      plugins: [build],
+    };
+  }
 
-registerHandlers(app);
+  return {
+    plugins: [dev],
+  };
+});
 ```
 
-登録内容を entry file から静的に確定できるようにすることで、生成する GAS グローバル関数を決定的にしています。
+`build` を通常の frontend build に含めると、server entry が Vite の build input になるため、frontend と backend の build は分離してください。
 
 ## 関連パッケージ
 
-アプリケーションの runtime と handler registration には `@gasboost/app` を利用してください。
+- `@gasboost/app` — GAS バックエンドランタイムと RPC 定義
+- `@gasboost/client` — フロントエンド側の型安全 RPC クライアント
+
+## License
+
+MIT

package/dist/build.d.ts

@@ -0,0 +1,3 @@
+import type { Plugin } from "vite";
+import type { GasboostOptions } from "./gasboost";
+export declare function createBuildPlugin(options: GasboostOptions): Plugin;

package/dist/dev.d.ts

@@ -0,0 +1,2 @@
+import type { Plugin } from "vite";
+export declare function createDevPlugin(entry: string): Plugin;

package/dist/gasboost.d.ts

@@ -3,4 +3,7 @@ export interface GasboostOptions {
     entry: string;
     envDir?: string;
 }
-export declare function gasboost(options: GasboostOptions): Plugin;
+export declare function gasboost(options: GasboostOptions): {
+    build: Plugin;
+    dev: Plugin;
+};

package/dist/index.js

@@ -114,11 +114,12 @@ function b(e) {
 	return t.join("\n");
 }
 //#endregion
-//#region src/gasboost.ts
+//#region src/build.ts
 function x(e) {
 	let t;
 	return {
-		name: "gasboost",
+		name: "gasboost:build",
+		apply: "build",
 		config() {
 			return _(e);
 		},
@@ -132,4 +133,89 @@ function x(e) {
 	};
 }
 //#endregion
-export { x as gasboost };
+//#region src/dev.ts
+var S = class extends Error {
+	constructor(e) {
+		super(e), this.name = "InvalidRpcRequestError";
+	}
+};
+function C(e) {
+	return {
+		name: "gasboost:dev",
+		apply: "serve",
+		configureServer(t) {
+			t.middlewares.use(async (n, r, i) => {
+				if (!n.url) {
+					i();
+					return;
+				}
+				let a = n.url.split("?")[0];
+				if (!a.startsWith("/__gasboost/")) {
+					i();
+					return;
+				}
+				let o = a.slice(12);
+				if (!o || o.includes("/")) {
+					i();
+					return;
+				}
+				if (n.method !== "POST") {
+					r.statusCode = 405, r.setHeader("Content-Type", "application/json; charset=utf-8"), r.end(JSON.stringify({ error: {
+						name: "MethodNotAllowedError",
+						message: "Only POST is allowed."
+					} }));
+					return;
+				}
+				try {
+					let { args: i } = await w(n), a = await (await t.ssrLoadModule(e)).default.dispatch(decodeURIComponent(o), ...i);
+					r.statusCode = 200, r.setHeader("Content-Type", "application/json; charset=utf-8"), r.end(a.contents);
+				} catch (e) {
+					r.statusCode = e instanceof S ? 400 : 500, r.setHeader("Content-Type", "application/json; charset=utf-8"), r.end(JSON.stringify({ error: e instanceof Error ? {
+						name: e.name,
+						message: e.message,
+						stack: e.stack
+					} : {
+						name: "UnknownError",
+						message: String(e)
+					} }));
+				}
+			});
+		}
+	};
+}
+function w(e) {
+	return new Promise((t, n) => {
+		let r = [];
+		e.on("data", (e) => {
+			r.push(typeof e == "string" ? Buffer.from(e) : e);
+		}), e.on("error", n), e.on("end", () => {
+			let e = Buffer.concat(r).toString("utf-8");
+			if (!e) {
+				t({ args: [] });
+				return;
+			}
+			let i;
+			try {
+				i = JSON.parse(e);
+			} catch {
+				n(new S("Invalid RPC request body. Expected valid JSON."));
+				return;
+			}
+			if (typeof i != "object" || !i || !("args" in i) || !Array.isArray(i.args)) {
+				n(new S("Invalid RPC request body. Expected { args: unknown[] }."));
+				return;
+			}
+			t({ args: i.args });
+		});
+	});
+}
+//#endregion
+//#region src/gasboost.ts
+function T(e) {
+	return {
+		build: x(e),
+		dev: C(e.entry)
+	};
+}
+//#endregion
+export { T as gasboost };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gasboost/vite",
-  "version": "0.1.0",
+  "version": "1.0.1",
   "description": "A Vite plugin for building @gasboost/app applications for Google Apps Script.",
   "keywords": [
     "google-apps-script",
@@ -36,7 +36,11 @@
     "vite": "^8.2.2"
   },
   "dependencies": {
-    "typescript": "^7.0.2"
+    "typescript": "^7.0.2",
+    "@gasboost/app": "1.0.1"
+  },
+  "publishConfig": {
+    "access": "public"
   },
   "scripts": {
     "typecheck": "tsc -p tsconfig.json --noEmit",