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

router / 導入ガイド

@ciderjs/city-gas

GAS環境用ファイルベースルーター

npm install --save @ciderjs/city-gas
このページの内容

@ciderjs/city-gas は、Google Apps Script (GAS) の HtmlService 環境および標準的なモダンブラウザ環境の両方で動作する、React および Vue 3 向けの型安全なファイルベースルーターライブラリです。クエリパラメータ ?page=... を用いた擬似的なパスルーティングにより、ローカル開発環境(ブラウザ)と本番環境(GAS の iframe サンドボックス)の差異を抽象化します。

概要と特徴

Google Apps Script の Web アプリケーション環境(HtmlService)では、iframe サンドボックスの制約によりブラウザ標準のパスベースルーティング(History API による /users/123 などのパス変更)が利用できません。@ciderjs/city-gas は、Vite プラグインによるファイルベースのルート自動生成と Zod スキーマによる静的・動的型検証を組み合わせ、モダンな SPA と同等のルーティング体験を提供します。

  • 環境自動判定 (Universal Adapter): 実行時に google.script の有無を判定し、GAS 環境では google.script.history / google.script.url、ブラウザ環境では window.history / window.location を自動的に切り替えて使用します。
  • ファイルベースルーティング: src/pages ディレクトリ配下の .tsx または .vue ファイルを走査し、静的ルート・動的ルート([param])・ネストされたレイアウト階層を自動生成します。
  • 静的解析による型生成と実行時バリデーション: 各ページでエクスポートされた Zod スキーマ(export const schema)を Vite プラグインが AST 解析し、TypeScript の型定義(.d.ts)とランタイムルートマップを自動生成します。
  • マルチフレームワーク対応: コアルーターとフレームワークアダプタを分離し、React(Hooks / Context)と Vue 3(Composables / Plugin)の双方に同一のルーティング機能を提供します。

動作要件

  • vite: >= 7(ルートおよび型定義の自動生成プラグインに必要)
  • zod: >= 4(パラメータのスキーマ定義および実行時バリデーションに必要)
  • react / react-dom: >= 18(React アダプタ @ciderjs/city-gas/react 使用時に必要)
  • vue: >= 3(Vue 3 アダプタ @ciderjs/city-gas/vue 使用時に必要)

インストール

パッケージマネージャーを使用して @ciderjs/city-gas と zod をインストールします。

.sh
# pnpm
pnpm add @ciderjs/city-gas zod

# npm
npm install @ciderjs/city-gas zod

# yarn
yarn add @ciderjs/city-gas zod

クイックスタート

1. Vite プラグインの設定

使用するフレームワーク(React または Vue 3)のプラグインとあわせて、@ciderjs/city-gas/plugin の cityGasRouter() を vite.config.ts に追加します。

vite.config.ts
.ts
// React の場合
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import { cityGasRouter } from '@ciderjs/city-gas/plugin';

export default defineConfig({
  plugins: [react(), cityGasRouter()],
});
vite.config.ts
.ts
// Vue 3 の場合
import { defineConfig } from 'vite';
import vue from '@vitejs/plugin-vue';
import { cityGasRouter } from '@ciderjs/city-gas/plugin';

export default defineConfig({
  plugins: [vue(), cityGasRouter()],
});

2. ページコンポーネントの作成

src/pages ディレクトリ配下にページコンポーネントを作成します。

src/pages/index.tsx
.tsx
// React の場合
export default function IndexPage() {
  return <div>Home Page</div>;
}
src/pages/index.vue
.vue
<!-- Vue 3 の場合 -->
<template>
  <div>Home Page</div>
</template>

3. エントリーポイントでのルーター初期化

Vite の起動またはビルド時に src/generated/routes.ts と src/generated/router.d.ts が自動生成されます。これらを読み込んでルーターを初期化します。

src/main.tsx
.tsx
// React の場合
import React from 'react';
import ReactDOM from 'react-dom/client';
import { createRouter } from '@ciderjs/city-gas';
import { RouterProvider } from '@ciderjs/city-gas/react';
import './generated/router.d';
import { pages, specialPages, dynamicRoutes } from './generated/routes';

const router = createRouter(pages, { specialPages, dynamicRoutes });

ReactDOM.createRoot(document.getElementById('root')!).render(
  <React.StrictMode>
    <RouterProvider router={router} />
  </React.StrictMode>,
);
src/main.ts
.ts
// Vue 3 の場合
import { createApp } from 'vue';
import { createRouter } from '@ciderjs/city-gas';
import { createRouterPlugin, RouterOutlet } from '@ciderjs/city-gas/vue';
import './generated/router.d';
import { pages, specialPages, dynamicRoutes } from './generated/routes';

const router = createRouter(pages, { specialPages, dynamicRoutes });

createApp(RouterOutlet).use(createRouterPlugin(router)).mount('#root');

基本的な使い方

Zod スキーマによるパラメータ定義と取得

各ページファイルから schema という名前の定数(z.object({...}))をエクスポートすることで、そのルートが受け取るクエリパラメータおよびパスパラメータの型とバリデーションルールを定義します。

  • 動的ルートのパスパラメータ(例:[userId])は、schema 内に記述しなくても自動的に { userId: string }(実行時は z.object({ userId: z.string() }))としてマージされます。
  • パスパラメータを数値や UUID としてバリデーション・型変換したい場合は、schema 内に同名のキーを定義します(例:userId: z.coerce.number() や productId: z.string().uuid())。schema 側の定義がデフォルトの string 型定義より優先されます。
  • URL クエリやパスから取得される生の値は文字列です。数値や真偽値を期待する場合は z.coerce.number() や z.coerce.boolean()、または .transform() を使用してください。
src/pages/users/[userId].tsx
.tsx
// React での定義例
import { z } from 'zod';
import { useParams } from '@ciderjs/city-gas/react';

export const schema = z.object({
  tab: z.enum(['profile', 'settings']).optional(),
  pageIndex: z.coerce.number().int().positive().optional(),
});

export default function UserDetailPage() {
  // userId (string), tab ('profile' | 'settings' | undefined), pageIndex (number | undefined) が推論される
  const params = useParams('/users/[userId]');

  return (
    <div>
      <h1>User: {params.userId}</h1>
      <p>Tab: {params.tab ?? 'default'}</p>
    </div>
  );
}

Vue 3 の <script setup> ブロック内では export const が使用できないため、通常の <script lang="ts"> ブロックを併用して schema をエクスポートします(<script> ブロック単体で記述する場合はそのままで問題ありません)。

src/pages/users/[userId].vue
.vue
<!-- Vue 3 での定義例 -->
<script setup lang="ts">
import { useParams } from '@ciderjs/city-gas/vue';

const params = useParams('/users/[userId]');
</script>

<script lang="ts">
import { z } from 'zod';

export const schema = z.object({
  tab: z.enum(['profile', 'settings']).optional(),
  pageIndex: z.coerce.number().int().positive().optional(),
});
</script>

<template>
  <div>
    <h1>User: {{ params.userId }}</h1>
    <p>Tab: {{ params.tab ?? 'default' }}</p>
  </div>
</template>

レイアウトと特殊ページ (specialPages)

src/pages 配下に特定の予約ファイル名でコンポーネントを作成すると、specialPages として認識され、レイアウトやフォールバック表示に使用されます。

ファイル名 配置場所 役割
_root.tsx / _root.vue src/pages/_root.*(直下のみ) アプリケーション全体の最上位レイアウト。すべてのページと _layout の外側をラップします。
_layout.tsx / _layout.vue src/pages/**/_layout.*(任意の階層) 配置されたディレクトリ配下のページおよびサブディレクトリに適用されるセクションレイアウト。
_404.tsx / _404.vue src/pages/_404.*(直下のみ) 未定義のルートへのアクセス時、またはパラメータのバリデーション失敗時に表示されるページ。未定義時は組み込みの DefaultNotFound が表示されます。
_loading.tsx / _loading.vue src/pages/_loading.*(直下のみ) ルーターの初期化完了前(router.isReady() === false の間)に表示されるローディング画面。未定義時は組み込みの DefaultLoading が表示されます。

例えば /parent/child/page(または /parent/child/index)がレンダリングされる際、RouterOutlet は <_root> -> <parent/_layout> -> <parent/child/_layout> -> <PageComponent {...params} /> の順序で入れ子にラップして描画します。React では { children }: { children: React.ReactNode } を Props として受け取り、Vue 3 では <template> 内に <slot /> を配置します。

src/pages/users/_layout.tsx
.tsx
// React のレイアウト実装例
import type React from 'react';

export default function UsersLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <div className="users-section">
      <aside>Users Menu</aside>
      <section>{children}</section>
    </div>
  );
}
src/pages/users/_layout.vue
.vue
<!-- Vue 3 のレイアウト実装例 -->
<template>
  <div class="users-section">
    <aside>Users Menu</aside>
    <section>
      <slot />
    </section>
  </div>
</template>

プログラムによる画面遷移 (navigate) とナビゲーションガード (beforeEach)

React の useNavigate()、Vue の useNavigate()、または router.navigate() を使用して画面遷移を行います。型定義が生成されている環境では、パラメータを持たないルート({})は第2引数 params を省略でき、必須パラメータを持つルートは第2引数 params の指定が必須となります。

src/components/NavButton.ts
.ts
const navigate = useNavigate();

// パラメータなしのルートへの遷移
navigate('/about');

// パラメータを持つルートへの遷移(userId はパスへ、tab はクエリ文字列へ展開される)
navigate('/users/[userId]', { userId: '123', tab: 'profile' });

// 履歴を置換して遷移 (replace モード)
navigate('/login', {}, { replace: true });

また、router.beforeEach を使用してプログラムによる遷移(navigate)の直前にガード処理を挟み込むことができます。複数のガードを登録した場合は登録順に直列実行されます。

src/main.ts
.ts
const unregister = router.beforeEach((to, from, next) => {
  if (to.name === '/admin' && !isAuthenticated()) {
    // 現在の遷移を中断し、指定ルートへ引数なしで新たに navigate('/login') を開始
    next('/login');
    return;
  }

  if (hasUnsavedChanges()) {
    // ナビゲーションを中断し、現在のルートを維持
    next(false);
    return;
  }

  // 次のガードへ進行(すべて通過すると遷移確定)
  next();
});

// ガードを解除する場合
unregister();

API リファレンス

パッケージエクスポート構成

サブパス 用途
@ciderjs/city-gas コアルーター API(createRouter、型定義、ユーティリティ関数)
@ciderjs/city-gas/plugin Vite プラグイン(cityGasRouter)
@ciderjs/city-gas/react React 用コンポーネントおよび Hooks
@ciderjs/city-gas/vue Vue 3 用プラグイン、コンポーネントおよび Composables

createRouter(pages, options?) (@ciderjs/city-gas)

ルーターインスタンスを生成します。

index.d.ts
.ts
function createRouter<
  RouteNames extends string,
  RouteParams extends Record<RouteNames, any> = RegisteredRouteParams,
  DefaultRouteName extends RouteNames = RouteNames,
  PageComponent = unknown,
>(
  pages: Record<RouteNames, PageInfo<PageComponent>>,
  options?: {
    specialPages?: Record<string, PageComponent>;
    defaultRouteName?: DefaultRouteName;
    dynamicRoutes?: DynamicRoute[];
    onValidateError?: (
      error: ZodError,
      context: { name: RouteNames; params: RouteParams[RouteNames] },
    ) =>
      | RouteNames
      | { name: RouteNames; params: RouteParams[RouteNames] }
      | void;
  },
): Router<RouteNames, RouteParams, PageComponent>;
プロパティ / 引数 型 デフォルト 説明
pages Record<RouteNames, PageInfo<PageComponent>> - ルート名をキー、PageInfo({ component, isIndex, schema? })を値とするオブジェクト。通常は generated/routes.ts の pages を渡します。
options.specialPages Record<string, PageComponent> {} _root, _layout, _404, _loading などの特殊ページマップ。generated/routes.ts の specialPages を渡します。
options.dynamicRoutes DynamicRoute[] [] 動的ルートのマッチング定義配列。generated/routes.ts の dynamicRoutes を渡します。
options.defaultRouteName DefaultRouteName '/' URL に page クエリが存在しない場合の初期ルート名。
options.onValidateError (error: ZodError, context) => RouteNames | ... undefined URL パラメータの Zod バリデーション失敗時に呼ばれるコールバック。リダイレクト先のルート名または { name, params } を返すと遷移し、未返却時は _404 になります。

Router インターフェースとユーティリティ (@ciderjs/city-gas)

createRouter が返すオブジェクトのメソッド・プロパティ一覧です。

プロパティ / 引数 型 デフォルト 説明
navigate (name, params?, options?: { replace?: boolean }) => void - 指定したルートへ遷移します。options.replace: true で履歴を追加せず置換します。
subscribe (listener: (route: Route) => void) => () => void - ルート変更リスナーを登録します。ready 状態であれば登録時に即座に現在のルートで1回呼び出されます。戻り値は購読解除関数です。
getCurrentRoute () => Route<RouteNames, RouteParams> - 現在のルートオブジェクト({ name, params })を返します。
beforeEach (guard: NavigationGuard) => () => void - ナビゲーションガードを登録します。戻り値は登録解除関数です。
isReady () => boolean - 環境アダプタの getLocation() による初回ロケーション解決が完了しているかどうかを返します。
pages Record<RouteNames, PageInfo<PageComponent>> - 登録されたページ定義マップ。
specialPages Record<string, PageComponent> - 登録された特殊ページ定義マップ。
dynamicRoutes DynamicRoute[] - 登録された動的ルート定義配列。
  • parseLocation(location: string): { name: string; params: any }
    クエリ文字列(例:'?page=/about&id=1')を解析し、ルート名とパラメータオブジェクトに変換します。?page=/index は '/' に正規化されます。
  • serializeParams(params: Record<string, any>): string
    パラメータオブジェクトを URL クエリ文字列(先頭の ? なし)にシリアライズします。
  • グローバル型登録 (Register):
    Vite プラグインが生成する router.d.ts が @ciderjs/city-gas モジュールの Register インターフェースを宣言マージ(Module Augmentation)することで、RegisteredRouteNames および RegisteredRouteParams を通じて useNavigate や useParams などの全 API にプロジェクト固有の型が自動注入されます。

cityGasRouter(options?) (@ciderjs/city-gas/plugin)

ページディレクトリの監視と型・ルート定義の自動生成を行う Vite プラグインです。

plugin.d.ts
.ts
interface Options {
  pagesDir?: string;
}
function cityGasRouter(options?: Options): PluginOption;
プロパティ / 引数 型 デフォルト 説明
pagesDir string 'src/pages' ページコンポーネントを探索するディレクトリパス(プロジェクトルートからの相対パスまたは絶対パス)。
  • 生成ファイル: src/generated/router.d.ts(型定義と declare module '@ciderjs/city-gas')および src/generated/routes.ts(pages, specialPages, dynamicRoutes のランタイム定義)。
  • HMR とキャッシュ動作: 開発サーバー実行中、pagesDir 配下のファイル追加(add)・変更(change)・削除(unlink)を監視し、mtimeMs が更新されたファイルのみ AST 解析を再実行します。生成結果の文字列が前回と同一である場合はファイル書き出しをスキップし、不要な再ビルドを防止します。

React Adapter API (@ciderjs/city-gas/react)

  • <RouterProvider router={router} children?={...} />: ルーターインスタンスを React Context に供給します。children を省略した場合は自動的に <RouterOutlet /> をレンダリングします。
  • <RouterOutlet />: 現在のルートに対応するページコンポーネントとレイアウト階層(_root, _layout)、および未準備時の _loading や未検出時の _404 を描画します。ページコンポーネントには現在の params が Props としても展開(<PageComponent key={name} {...params} />)されます。
  • useNavigate(): router.navigate 関数を返します。
  • useParams(routeName): 現在のルートのパラメータ(P[R])を返します。引数にルート名リテラル(例:'/users/[userId]')を渡すことで、そのルート固有のパラメータ型に絞り込まれます。
  • useRoute(): 現在のルートオブジェクト { name, params } を返します。
  • useRouter(): Router インスタンス自体を返します。
  • ※ すべての状態購読 Hooks(useRoute, useParams, RouterOutlet)は内部で React.useSyncExternalStore を使用しています。

Vue 3 Adapter API (@ciderjs/city-gas/vue)

  • createRouterPlugin(router): Vue アプリケーションインスタンス(app.use(...))にルーターを登録するためのプラグインを生成します。
  • RouterOutlet: 現在のルートに対応するコンポーネントとレイアウト階層を描画する Vue コンポーネントです。createApp(RouterOutlet) のようにルートコンポーネントとして直接マウントすることも、テンプレート内で <RouterOutlet /> として使用することも可能です。ページコンポーネントには params が Props として渡されます。
  • useNavigate(): router.navigate 関数を返します。
  • useParams(routeName): 現在のルートのパラメータを格納した読み取り専用 Ref(DeepReadonly<Ref<P[R]>>)を返します。テンプレート外で値を参照する場合は params.value.xxx のように .value を経由します。
  • useRoute(): 現在のルートオブジェクト { name, params } を格納した読み取り専用 Ref(DeepReadonly<Ref<Route<R, P>>>)を返します。
  • useRouter(): Router インスタンスを返します。
  • useRouterContext(): Provide / Inject された { router } コンテキストオブジェクトを返します。

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

ファイルベースルーティング仕様と優先順位

デフォルトでは src/pages ディレクトリ内の .tsx および .vue ファイルがスキャンされ、以下の規則でルート名に変換されます。内部的にはすべて ?page=<ルート名> として解決されます。

ファイルパス ルート名 (RouteNames) URL クエリ表現 種別
src/pages/index.tsx / ?page=/ (または ?page=/index, 指定なし) インデックスルート
src/pages/about.tsx /about ?page=/about 静的ルート
src/pages/users/index.tsx /users ?page=/users ネストされたインデックスルート
src/pages/users/show.tsx /users/show ?page=/users/show 静的ルート
src/pages/users/[userId].tsx /users/[userId] ?page=/users/123 動的ルート
src/pages/shops/[shopId]/items/[itemId].tsx /shops/[shopId]/items/[itemId] ?page=/shops/s1/items/i9 複数パラメータ動的ルート
  1. インデックスファイルと通常ファイルの競合: 同一のルート名になるファイルが複数存在する場合(例:src/pages/users.tsx と src/pages/users/index.tsx)、ディレクトリ内の index ファイル(src/pages/users/index.tsx)が優先されます。競合発生時はビルド・生成時にコンソールへ警告が出力され、通常ファイルは無視されます。
  2. 静的ルートと動的ルートの優先順位: 実行時のルート解決(resolveRoute)では、常に静的ルートの完全一致検索が先に行われ、一致する静的ルートが存在しない場合のみ動的ルートの正規表現マッチングが実行されます(例:/users/show と /users/[userId] が両方存在する場合、?page=/users/show は常に /users/show に解決されます)。

パラメータのシリアライズとパース仕様

serializeParams および parseLocation は以下の規則でパラメータを変換します。

データ型 シリアライズ時の挙動 (navigate) パース時の挙動 (parseLocation)
プリミティブ (string, number, boolean) String(value) で文字列化し設定 文字列として取得(その後 Zod スキーマで検証・変換)
undefined / null クエリ文字列から除外 -
配列 (Array) 同一キーで複数回 append (?tags=a&tags=b) 同一キーが複数存在する場合は配列 string[] として取得(要素が1つの場合は単一文字列)
オブジェクト (Object) JSON.stringify(value) で JSON 文字列化 値が { で始まり } で終わる場合、JSON.parse を試行(失敗時は文字列のまま保持)

実行時バリデーションとエラーハンドリング

  1. URL 変更・初期ロード時のバリデーション失敗: createRouter の options.onValidateError が指定されている場合はそのフックが呼び出されます。フックがルート名(string)または { name, params } を返した場合はそのルートへフォールバックし、未指定または void を返した場合はコンソールに警告を出力して _404 ルートへフォールバックします。
  2. router.navigate() 呼び出し時のバリデーション失敗: 開発時の実装ミス(不正なパラメータの渡し間違い)を即座に検知できるよう、[city-gas] Navigation aborted: Invalid params for "<routeName>": ... という例外(Error)をスローし、遷移を中断します。

環境アダプタ仕様 (GAS / ブラウザ)

実行時に 'google' in globalThis && google.script が真であれば gasAdapter、それ以外は browserAdapter を自動選択します。

操作 Browser Adapter (browser.ts) GAS Adapter (gas.ts)
初回ロケーション取得 (getLocation) Promise.resolve(window.location.search) google.script.url.getLocation(cb) のコールバック結果をクエリ文字列に変換
履歴追加 (push) window.history.pushState({}, '', url) google.script.history.push({}, params, hash)
履歴置換 (replace) window.history.replaceState({}, '', url) google.script.history.replace({}, params, hash)
履歴変更監視 (onChange) window.addEventListener('popstate', ...) google.script.history.setChangeHandler(...)

GAS の WebAppLocationType には単一値を持つ parameter(Record<string, string>)と配列値を持つ parameters(Record<string, string[]>)の2種類が存在します。gasAdapter は location.parameters が存在する場合はそれを優先して全要素を展開し、存在しない場合は location.parameter にフォールバックします。

制限事項と注意点

  • 予約語 page の使用禁止: ルーティング先の識別に ?page=... クエリパラメータを使用するため、ページの schema 定義内で page というプロパティ名を使用するとビルド時にエラー([city-gas] Reserved word "page" is not allowed in schema definition.)がスローされます。ページネーション等を実装する場合は pageIndex や pageNum などの別名を使用してください。
  • スキーマ定義のインライン記述制約: Vite プラグインは ts-morph を用いた静的 AST 解析によって export const schema から型定義を生成します。同一ファイル内で宣言された変数参照や import { z as customZ } from 'zod' のようなエイリアスインポートには対応していますが、別ファイルからインポートしたスキーマ変数を再エクスポートする構成は解析対象外となります。schema は必ず各ページファイル内で定義してください。
  • zodToTs がサポートする Zod メソッドと .transform() の挙動: プリミティブ、z.coerce.*、z.literal、z.enum、z.nativeEnum、z.object、z.array、z.record、z.tuple、z.union、z.intersection、および .optional() / .nullable() / .nullish() / .default() に対応しています。.min(), .email(), .refine(), .transform() 等のメソッドチェーンを使用した場合、静的型生成(router.d.ts)では変換前の基底型が維持される点に注意してください。
  • GAS 環境における URL 長の制限: Google Apps Script 環境では URL の最大長に制限(約 2KB 程度)があります。巨大なオブジェクトや配列をルートパラメータ経由で受け渡すことは避け、グローバルステート(Pinia, Zustand 等)や sessionStorage、GAS の PropertiesService / CacheService などを利用してください。
  • ページファイルのトップレベル副作用の回避: 自動生成される src/generated/routes.ts はすべてのページコンポーネントとスキーマを静的に import するため、アプリ起動時に全ページファイルのトップレベルコードが評価されます。API 通信、google.script.run の呼び出し、DOM 操作、タイマー登録などは必ずコンポーネントのライフサイクル内(React の useEffect、Vue の onMounted 等)に記述してください。

ライセンス

MIT License