Build an Astro site on WordPress.

前提条件

• Node 20 以上とターミナル。
• WordPress サイト（6.9 以上）に DesignSetGo Apps プラグインを有効化したもの。
• WordPress の アプリケーションパスワード （そのサイト用）。

Freeは1つのアクティブな静的アプリをサポートします。ライブソース動的ルート（ wp:posts、 wc:products、など） Pro.

プロジェクトのスキャフォールド

npx @designsetgo/cli apps init my-astro-site --astro
cd my-astro-site
npm install

Astro スターターには astro.config.mjs がすでに DSGo マニフェストに接続されており、ベース Layout.astro、3つのサンプルページ、 CLAUDE.md （エージェント向けにブリッジを文書化）、そして dsgo-app.json （ホームルートがあらかじめ宣言済み）が含まれています。

astro.config.mjs

DSGo が配信できるバンドルを生成するために、Astro には3つのものが必要です。 base プラグインがアプリをマウントするURLに一致するもの、静的出力、そしてすべてのページが次の形式で出力されるようにディレクトリ形式のルートが必要です。 some-route/index.html.

import { defineConfig } from 'astro/config';
import { readFileSync } from 'node:fs';
import { fileURLToPath } from 'node:url';

const manifest = JSON.parse(
  readFileSync(fileURLToPath(new URL('./dsgo-app.json', import.meta.url)), 'utf8'),
);

export default defineConfig({
  base: manifest.mount?.mode === 'root' ? '/' : `/apps/${manifest.id}/`,
  output: 'static',
  trailingSlash: 'always',
  build: { format: 'directory' },
  vite: { build: { assetsInlineLimit: 0 } },
});

• base — はマニフェストを読み込むため、 mount.mode の値を "prefixed" と "root" の間で切り替えても設定ファイルの編集は不要です。Astro は内部アセット URL を自動的に書き換えます。
• build.format: 'directory' — src/pages/about.astro は次の場所に出力します。 dist/about/index.htmlこれはマニフェストの file フィールドが参照する場所です。
• vite.build.assetsInlineLimit: 0 — は Vite が小さなアセットを <script> としてインライン化するのを防ぎます。DSGo の CSP サニタイザーはこれを拒否します。

マニフェスト

Astro が生成するすべてのページは dsgo-app.json の routes. に宣言する必要があります。 file パスはバンドル相対（ dist/を基準）なので、Astro ページが src/pages/pricing.astro にあり、 format: 'directory' の場合、次のようにマッピングされます。 file: "pricing/index.html".

{
  "manifest_version": 1,
  "id": "my-astro-site",
  "name": "My Astro site",
  "version": "0.1.0",
  "isolation": "inline",
  "entry": "index.html",
  "routes": [
    { "path": "/",        "file": "index.html",         "title": "Home" },
    { "path": "/about",   "file": "about/index.html",   "title": "About" },
    { "path": "/pricing", "file": "pricing/index.html", "title": "Pricing" }
  ],
  "permissions": { "read": ["site_info"], "write": [] }
}

マニフェストが CLI がアップロードするバンドルの 内側 に確実に含まれるようにしてください。最も簡単な方法は Astro の public/ フォルダに配置することです（そのまま dist/にコピーされます）。またはビルドスクリプトでコピーすることもできます。 "build": "astro build && cp dsgo-app.json dist/".

routes[0] には path: "/". ホームルートは必須です。

ページの追加

通常通り Astro ページを作成してください。DSGo のビルドプラグイン、特別なコンポーネント、必須の getStaticPaths コントラクトはありません。ただの Astro です。

---
import Layout from '../../layouts/Layout.astro';
---
<Layout title="About">
  <h1>About this site</h1>
  <p>Built with Astro, deployed to WordPress.</p>
</Layout>

マニフェストの routes に対応するエントリを追加すると、設定されたベースパスでページが解決されます。

ページ間のリンク

Astro はアセット URL のみを書き換え、 href の値は書き換えません。内部リンクには import.meta.env.BASE_URL を使ってください。プレフィックスマウントとルートマウントの両方でコード変更なしに動作します。

<a href={`${import.meta.env.BASE_URL}pricing`}>Pricing</a>
<a href={`${import.meta.env.BASE_URL}about`}>About</a>

アプリ内のプログラム的なナビゲーションには dsgo.router.navigate(path) — を使ってください。親はアプリのマウント内に新しいパスが収まることを検証し、ブラウザの URL を安全に更新します。直接の history.pushState マウント外への呼び出しはブロックされます。

WordPress データの読み込み

任意の Astro ページやコンポーネントで @designsetgo/app-client をインポートします。 <script>. ブリッジは表示時にブラウザ上で動作するため、ページ自体はクローラーがインデックスできる静的アセットのままです。

---
import Layout from '../../layouts/Layout.astro';
---
<Layout title="Latest posts">
  <h1>From the blog</h1>
  <ul id="posts"></ul>
</Layout>

<script>
  import { dsgo } from '@designsetgo/app-client';

  await dsgo.ready;
  const { items } = await dsgo.posts.list({ per_page: 5 });

  const ul = document.getElementById('posts');
  for (const post of items) {
    const li = document.createElement('li');
    const a = document.createElement('a');
    a.href = post.link;
    a.textContent = post.title;
    li.appendChild(a);
    ul.appendChild(li);
  }
</script>

ブリッジの全機能（posts、pages、user、media、AI、commerce、storage、abilities、email、HTTP、router）は ブリッジリファレンス.

権限の宣言

ブリッジメソッドはマニフェストで宣言された内容によって制御されます。デプロイ前に呼び出しに必要な権限を追加してください。追加しないとプリフライトでインストールが拒否されます。

"permissions": {
  "read": ["site_info", "posts", "user"],
  "write": []
}

権限はインストール時にサイト管理者に提示され、7つのバケットにグループ化され、各バケットには1文の説明が付きます。 権限リファレンス.

ブロックマークアップのレンダリング

ブリッジから返される投稿やページには、ブロック形式の HTML が post.content. として含まれています。DOM に挿入するとマークアップは得られますが、WordPress がフロントエンドで出力するスタイルは含まれません（Cover に min-height がなく、Columns が flex でないなど）。マニフェストでオプトインして、レンダリング後に SDK ヘルパーを呼び出してください。

"content": { "blockStyles": ["core", "auto"] }

import { dsgo } from '@designsetgo/app-client';

const post = await dsgo.posts.get(id);
container.innerHTML = post.content;
dsgo.content.applyBlockStyles(post);   // idempotent, safe on every route change

パートナープラグインのスタイルには "designsetgo" を、テーマのコンパイル済み "themeStyles": "global" を配信するには theme.json CSS を追加してください。結合ペイロードは投稿あたり 256 KB に制限されています。

ライブデータからの動的ルート

WordPress エディターが管理するコンテンツ（投稿、製品、カスタム投稿タイプ）については、アイテムごとに Astro ページを用意するのではなく、 :param プレースホルダーを持つ1つのテンプレートルートを宣言してライブデータセットに向けてください。プラグインはリクエスト時にこれを解決し、フィールドをテンプレートに代入します。

{
  "path": "/posts/:slug",
  "file": "post/index.html",
  "dataset": { "source": "wp:posts", "id_field": "slug" }
}

にあるテンプレート src/pages/post.astro のテンプレートは {{title}}, {{excerpt}}, {{content}} プレースホルダー（サーバー側で代入）を使用します。より豊かなレンダリングには、 dsgo.context.routeParams.slug でブリッジを呼び出して完全な投稿オブジェクトを取得します。

ライブソースは Pro. の機能です。Free ではアプリのインストールと静的ルートは機能しますが、ライブソースルートは Pro が有効になるまで非アクティブです。結果は app+route+version ごとに1時間キャッシュされ、対応する投稿タイプへの保存と削除により自動的に無効化されます。

@designsetgo/astro: バーティカルパックコンポーネント

WooCommerce フロントエンド（将来的には不動産、フィットネス、フード、地域サービスにも対応予定）を構築している場合、 @designsetgo/astro はすべての DSGo バーティカルパック用のビルド済み Astro コンポーネントを含む独立した npm パッケージです。また、コンポーネントに必要な権限、abilities、commerce エンドポイントをビルド時に自動的に dsgo-app.json にマージする小さな Astro インテグレーションも含まれています。v0.1.0 では 14 個の WooCommerce コンポーネントが含まれています。

Claude Code、Cursor、または Codex でプロジェクトを vibe-coding している場合に便利です。AI がコンポーネントのインポートを追加・削除するにつれて、インテグレーションは dsgo-app.json を正確に保ちます。インポートが実際に必要とするものからマニフェストがずれると CI のビルドが失敗します。

パッケージのインストール

npm install @designsetgo/astro

Astro 4 または 5 はすでにお持ちのピア依存関係です。ブリッジクライアント（ @designsetgo/app-client）はオプションのピアです。コンポーネントが推移的にインポートするため、自分の <script> ブロックにのみ必要です。

インテグレーションの追加

import { defineConfig } from 'astro/config';
import dsgoAstro from '@designsetgo/astro/integration';

export default defineConfig({
  integrations: [
    dsgoAstro({ manifest: './dsgo-app.json' }),
  ],
});

内の1行 astro.config.mjs. に1行追加するだけです。ビルドのたびにインテグレーションはプロジェクト内の @designsetgo/astro/<pack> インポートをスキャンし、各コンポーネントのマニフェストを node_modulesから読み込み、必要な権限を dsgo-app.json にユニオンし（他のすべてのキーを保持）、 .astro/dsgo-window.d.ts シムを出力して window.dsgo が実際に宣言した権限に対してオートコンプリートできるようにします。

コンポーネントのインポート

---
import { SmartCartUpsell, ProductQa } from '@designsetgo/astro/woo';
---
<SmartCartUpsell count={4} heading="You might also like" />
<ProductQa productId={42} />

各コンポーネントは独自のマークアップをレンダリングし、スコープ付き CSS を持ち、 data-dsgo-component スラッグをキーとする IIFE 内で小さなクライアントバンドルを自動起動します。同じページ上の2つのコンポーネントはスラッグで分離されており、バンドル A の mount はバンドル B のルートに対して発火しません。

コンポーネントカタログ（v0.1.0）

WooCommerce パック（ @designsetgo/astro/woo）:

すべてのコンポーネントは examples/woo-*/のスタンドアロンバンドルと動作互換性があり、パリティテストとプリコミットフックで同期が保たれます。説明、オプション、トラブルシューティングを含む完全なカタログは パッケージ README.

書き込みモードと確認モード

mode: 'write' （デフォルト）はコンポーネントが権限を追加する際に dsgo-app.json を直接書き換えます。 mode: 'check' はファイルが古い場合に差分を表示してビルドを非ゼロで終了します。 'check' を CI で使用すると、マニフェストの再ステージを忘れた場合にビルドが失敗します。

dsgoAstro({
  manifest: './dsgo-app.json',
  mode: process.env.CI ? 'check' : 'write',
})

マージは追加のみです。インテグレーションは権限を削除しません。ローカル開発モードではマージを 200ms デバウンスするため、インポートを追加するファイルを保存してもマニフェストが連続更新されません。

プレフィックスマウント（デフォルト）

がない場合 mount ブロックなしでは、アプリは /apps/<id>/.... で配信されます。既存の WP サイトの横にツール、マイクロサイト、マーケティングページを追加するのに適しており、 /.

ルートマウント（サイト全体）

Astro アプリをサイト そのもの にするには、マニフェストに追加してください。

"mount": { "mode": "root" }

アプリは /. で配信されます。宣言した Astro ルートが WordPress が配信するはずだった URL を占有し、WP が 404 を返すはずだったパスはルートテーブルにフォールスルーします。実際の WP ページ、投稿、アーカイブ、フィードはデフォルトで優先されます。ルートモードは 追加するのであってシャドウしません。そのため編集者は引き続き wp-admin で公開できます。

Astro ルートが意図的に WP をオーバーライドする必要がある場合（例: アプリでレンダリングされた /blog が wp:posts を元にしており、WP のネイティブブログアーカイブと衝突する場合）、そのルートに claim: "always" を追加してください。 ルートのクレーム.

ビルドとデプロイ

npx @designsetgo/cli apps login --site https://yoursite.com
npx @designsetgo/cli apps deploy --build

--build は最初に npm run build を実行します。次に CLI が dist/を zip 圧縮し、マニフェストを検証し、機能の差分を表示して、サイトの REST エンドポイントにバンドルを送信します。 deploy を再実行すると、同じアプリ ID で既存のインストールをアトミックに更新します。

Free では、 apps init --astro とローカルビルドは機能しますが、 deploy は wp-admin の バンドルアップロード （Path B）にフォールバックします。Pro ではターミナルから直接デプロイできます。

キャッシュ

• 静的アセットは自己バストします。 Astro と Vite はコンテンツハッシュ付きのファイル名（ app.BYFSNV21.css）を出力します。新しいビルド = 新しいハッシュ = エッジキャッシュの自動バスト。 max-age を1年に設定しても安全です。
• HTML ルートは匿名訪問者に対して公開キャッシュ可能 です。ユーザーごとのデータは SSR された HTML ではなく、実行時にブリッジを通じて流れます。
• ブリッジ呼び出し（ /wp-json/dsgo/v1/*）はキャッシュしてはいけません。 ブリッジは Cache-Control: no-storeを送信します。CDN の「Cache Everything」ルールで上書きしないでください。
• ルートマウントのアセット URL は /wp-content/uploads/designsetgo-apps/<id>/... に書き換えられ、nginx が PHP をバイパスして直接配信します。

詳細なガイダンス: メインドキュメントのキャッシュ & CDN.

よくある落とし穴

デプロイ時にインラインスクリプトが拒否される

CSP サニタイザーはインライン <script> の本体を拒否します。 vite.build.assetsInlineLimit: 0 の astro.config.mjs に設定して Vite がスクリプトを外部ファイルとして出力するようにしてください。サードパーティのオリジンには、ホストを runtime.csp.script_src.

デプロイ後にページが 404 を返す

すべての URL は routes. に宣言する必要があります。 file パスはバンドル相対（ dist/ ルート）です。 format: 'directory'、 src/pages/about.astro は次にマッピングされます。 about/index.html（ about.html.

ルートマウントアセットの 404

マネージドホスト（GoDaddy MWP、WP Engine）では、nginx が WordPress の実行前に .css/.js/.svg リクエストを高速パス処理する場合があります。バンドルアセット URL を実際のアップロードパスに書き換える DSGo Apps 0.1.1 以上が必要です。アップグレードしてから再デプロイしてください。 トラブルシューティング.

dsgo-app.json がバンドルに含まれていない

マニフェストは CLI が zip 圧縮する際に dist/ の内部に存在する必要があります。Astro の public/ フォルダに配置するか、ビルド後にコピーしてください。 "build": "astro build && cp dsgo-app.json dist/".

ルートマウントに切り替えるとリンクが壊れる

ハードコードされた /apps/<id>/ の href は /. で解決されません。常に ${import.meta.env.BASE_URL}path を使ってリンクしてください。両方のマウントモードでコード変更なしに動作します。

次に進む

• Bridge API 完全版 — すべてのメソッド、エラーコード、権限スコープ
• マニフェストリファレンス — 完全な dsgo-app.json スキーマ
• CLI コマンド — init, deploy, doctor、マルチサイトフラグ
• 権限 — 7つのバケットのインストールダイアログと各権限が許可する内容
• ナラティブ版 — 同じワークフロー、ウォークスルー形式

不足している点や不明な点がありますか？ Issue を開く.