サイトのデプロイ

このページは、Timeline DSL 本体やこのドキュメントサイトを保守する開発者向けです。.tdsl ファイルを使って年表を作る利用者向けの手順ではありません。

このドキュメントサイトは Cloudflare Pages の GitHub integration で公開します。GitHub Actions は CI として pnpm build を確認し、公開と Preview URL の作成は Cloudflare Pages に任せます。

前提

Cloudflare Pages project は timeline-dsl、production branch は main とします。

Cloudflare Pages の Build settings は以下にします。

| Setting | Value | | ---------------------- | ---------------- | | Root directory | site | | Build command | pnpm build | | Build output directory | dist | | Deploy command | 設定項目が出ない |

Cloudflare Pages の build image は dependency install を自動実行します。Build command に pnpm install --frozen-lockfile && pnpm build を入れても build はできますが、install が二重になるため pnpm build のみにします。

Deploy command が必須になっている場合や、非本番ブランチのデプロイコマンドが表示されている場合は、Pages ではなく Workers Builds の設定画面です。Workers Builds は build command の後に Wrangler の deploy command を実行する仕組みですが、このサイトは静的な Pages site として運用するため使いません。

実行タイミング

| Trigger | 用途 | Pages branch | | ------------------- | --------------------------------- | ------------ | | pull_request | Preview deployment を作成 | PR branch | | push to main | 本番公開 | main | | release.published | deploy trigger としては使わない | - | | workflow_dispatch | GitHub Actions の CI を手動再実行 | - |

pull request では GitHub Actions の Site build workflow と Cloudflare Pages の Preview deployment がそれぞれ実行されます。

Preview 確認

Cloudflare Pages の Preview URL は GitHub PR の checks、Deployments、または Cloudflare Pages dashboard から確認します。

1. PR の Cloudflare Pages check または Deployments から Preview URL を開く。
2. Preview URL で / が表示できることを確認する。
3. Preview URL で /docs/ が表示できることを確認する。
4. Playground を含む PR では Preview URL に対して smoke を実行する。

cd site
PLAYGROUND_BASE_URL="https://<preview>.pages.dev" pnpm smoke:playground

smoke:playground は /playground/、/wasm/tdsl_wasm.js、/wasm/tdsl_wasm_bg.wasm を HTTP で確認します。WASM asset の 404、.wasm の MIME type 不一致、未バージョン asset に対する強すぎる cache policy がある場合は失敗します。

Playground の画面操作まで確認する場合は Playwright package と Chromium を利用できる環境で browser smoke を実行します。Playwright は CI/build の必須依存には含めません。スクリーンショットは生成せず、artifact として repo には残しません。

cd site
PLAYGROUND_BASE_URL="https://<preview>.pages.dev" pnpm smoke:playground:browser

browser smoke は以下を確認します。

• /playground/ が表示される。
• 初期サンプルで data-smoke="playground-preview" 内に SVG preview が出る。
• data-smoke="playground-editor" の入力を壊すと data-smoke="playground-diagnostics" に error が出る。
• 入力を戻すと SVG preview が復帰する。
• WASM asset を 404 にした場合に、読み込み失敗がユーザーに見える。

Playground 実装では smoke 用に以下の属性を維持します。

| Target | Selector | | --------------------- | ------------------------------------- | | editor | data-smoke="playground-editor" | | preview container | data-smoke="playground-preview" | | diagnostics container | data-smoke="playground-diagnostics" |

エラー対応

Cloudflare build log に Worker Name、Executing user deploy command: npx wrangler deploy、Non-production branch deploy command が出ている場合は、Workers Builds として作成されています。Cloudflare dashboard で新しい Pages project を作成し、Pages の Import an existing Git repository からこの repository を接続してください。

Workers Builds として継続する場合は Wrangler 設定と Workers Static Assets 用の deploy command が必要になりますが、この LP/document サイトでは不要です。Missing file or directory: public/.assetsignore は Wrangler が Workers/Astro 用の追加セットアップを試みた結果で、Pages project として作り直すことで解消します。

参考:

• Cloudflare Pages build configuration
• Cloudflare Workers Builds configuration
• Cloudflare Pages preview deployments

ローカル確認

cd site
pnpm install --frozen-lockfile
pnpm build

Playground を実装したブランチでは、ローカル preview に対しても smoke を実行します。

cd site
pnpm build
pnpm preview -- --host 127.0.0.1 --port 4321

別 terminal で実行します。

cd site
PLAYGROUND_BASE_URL="http://127.0.0.1:4321" pnpm smoke:playground
PLAYGROUND_BASE_URL="http://127.0.0.1:4321" pnpm smoke:playground:browser

WASM bundle の更新

Playground と runnable docs から Timeline DSL WASM を使う場合、LP 側の呼び出し口は src/lib/tdsl-wasm.ts に集約します。Astro / Starlight のコンポーネントから tdsl_wasm.js や wasm-bindgen 生成物を直接 import しないでください。

timeline-dsl v1.2.0 以降は、GitHub Release に tdsl-wasm-<version>.tar.gz が添付されます。LP 側ではその wasm-pack 生成物を public/wasm/ に vendoring します。npm package 配布へ移行した場合も、差し替え対象は src/lib/tdsl-wasm.ts、public/wasm/、scripts/smoke-tdsl-wasm.mjs、scripts/smoke-playground.mjs、この更新手順に限定します。

更新時に確認するファイルは以下です。

| File | 確認内容 | | ------------------------------------ | ------------------------------------------ | | src/lib/tdsl-wasm.ts | import path、fallback message、公開 API 名 | | public/wasm/tdsl_wasm.js | wasm-bindgen の JS glue | | public/wasm/tdsl_wasm.d.ts | TypeScript 型 | | public/wasm/tdsl_wasm_bg.wasm | WASM binary | | public/wasm/tdsl_wasm_bg.wasm.d.ts | WASM binary import 型 | | public/wasm/package.json | package metadata | | scripts/smoke-tdsl-wasm.mjs | Node smoke が呼ぶ export 名 | | scripts/smoke-playground.mjs | Preview smoke の asset path と画面操作 |

通常は GitHub Release asset から WASM bundle を取得します。<version> には適用したい release tag（例: v1.4.0）を指定します。最新タグは Releases ページ で確認できます。

cd ../timeline-dsl-lp
curl -L "https://github.com/keroway/timeline-dsl/releases/download/<version>/tdsl-wasm-<version>.tar.gz" -o /tmp/tdsl-wasm.tar.gz
tar -xzf /tmp/tdsl-wasm.tar.gz -C site/public/wasm

本体 repo の手元の成果物を使う場合は、先に WASM を更新します。

cd ../timeline-dsl
wasm-pack build crates/tdsl-wasm --target web --out-dir apps/webui/src/wasm --no-opt

生成物を LP repo に同期します。

cd ../timeline-dsl-lp
cp ../timeline-dsl/apps/webui/src/wasm/tdsl_wasm.js site/public/wasm/tdsl_wasm.js
cp ../timeline-dsl/apps/webui/src/wasm/tdsl_wasm.d.ts site/public/wasm/tdsl_wasm.d.ts
cp ../timeline-dsl/apps/webui/src/wasm/tdsl_wasm_bg.wasm site/public/wasm/tdsl_wasm_bg.wasm
cp ../timeline-dsl/apps/webui/src/wasm/tdsl_wasm_bg.wasm.d.ts site/public/wasm/tdsl_wasm_bg.wasm.d.ts
cp ../timeline-dsl/apps/webui/src/wasm/package.json site/public/wasm/package.json

更新後は smoke と build を実行します。

cd site
pnpm smoke:wasm
pnpm build

Playground を含む更新では、ローカル preview または Cloudflare Pages Preview に対して pnpm smoke:playground も実行します。

WASM wrapper が対象にするのは静的な .tdsl の検証、IR 生成、SVG/HTML レンダリングです。Wikidata import の解決やネットワーク取得はブラウザ版 WASM では対応外とし、Playground 側では diagnostic として扱います。