Build an Astro site on WordPress.

Voraussetzungen

• Node 20+ und ein Terminal.
• Eine WordPress-Site (6.9+) mit dem DesignSetGo Apps Plugin aktiviert.
• Ein WordPress Anwendungspasswort für diese Site.

Free umfasst 1 aktive statische App. Live-Source-Dynamic-Routes ( wp:posts, wc:products, usw.), unbegrenzte aktive Apps und CLI Deploy erfordern Pro.

Projekt aufsetzen

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

Das Astro-Starter-Template enthält eine astro.config.mjs bereits mit dem DSGo-Manifest verbunden, eine Basis- Layout.astro, drei Beispielseiten, eine CLAUDE.md die die Bridge für Agenten dokumentiert, und eine dsgo-app.json mit der bereits vordefinierten Home-Route.

astro.config.mjs

Astro benötigt drei Dinge, um ein Bundle zu erzeugen, das DSGo ausliefern kann: eine base die der URL entspricht, unter der das Plugin die App einbindet, statische Ausgabe und Verzeichnisformat-Routen, damit jede Seite als 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 — liest das Manifest, sodass das Umschalten von mount.mode zwischen "prefixed" und "root" erfordert keine Konfigurationsbearbeitung. Astro schreibt interne Asset-URLs um, um sie anzupassen.
• build.format: 'directory' — src/pages/about.astro gibt aus als dist/about/index.html, das ist das, was das Manifest ist file Feld des Manifests referenziert.
• vite.build.assetsInlineLimit: 0 — verhindert, dass Vite kleine Assets als <script> Inhalt einbettet, was der DSGo-CSP-Sanitizer ablehnt.

Das Manifest

Jede von Astro erzeugte Seite muss in dsgo-app.json unter routes. Der file Pfad ist bundle-relativ (relativ zu dist/), also wird eine Astro-Seite unter src/pages/pricing.astro mit format: 'directory' zugeordnet zu 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": [] }
}

Stelle sicher, dass das Manifest innerhalb das Bundle, das die CLI hochlädt. Der einfachste Weg ist, es in Astro's public/ Ordner (es wird wörtlich in dist/kopiert), oder lass das Build-Skript es kopieren: "build": "astro build && cp dsgo-app.json dist/".

routes[0] muss haben path: "/". Die Home-Route ist obligatorisch.

Seiten hinzufügen

Schreiben Sie Astro-Seiten wie gewohnt. Es gibt kein DSGo-Build-Plugin, keine speziellen Komponenten und nichts Erforderliches getStaticPaths Vertrag, nur Astro.

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

Füge den passenden Eintrag unter routes im Manifest hinzu und die Seite wird unter dem konfigurierten Basispfad aufgelöst.

Zwischen Seiten verlinken

Astro schreibt nicht um href Werte nicht um, nur Asset-URLs. Für interne Links verwende import.meta.env.BASE_URL damit sowohl Präfix- als auch Root-Mounts ohne Code-Änderungen funktionieren:

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

Für programmatische Navigation innerhalb der App bevorzuge dsgo.router.navigate(path) — der Parent validiert, dass der neue Pfad innerhalb des App-Mounts bleibt, und aktualisiert die Browser-URL sicher. Direkte history.pushState Aufrufe außerhalb des Mounts werden blockiert.

WordPress-Daten lesen

Importiere @designsetgo/app-client in einer beliebigen Astro-Seite oder Komponente <script>. Die Bridge läuft zur Anzeigezeit im Browser, sodass die Seite selbst ein statisches Asset bleibt, das Crawler indexieren können.

---
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>

Die vollständige Bridge-Oberfläche (Beiträge, Seiten, Benutzer, Medien, KI, Commerce, Speicher, Abilities, E-Mail, HTTP, Router) ist dokumentiert in der Bridge-Referenz.

Berechtigungen deklarieren

Bridge-Methoden werden durch das, was das Manifest deklariert, gesperrt. Füge die Berechtigung, die der Aufruf benötigt, vor dem Deployment hinzu, sonst wird die Installation beim Preflight abgelehnt.

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

Berechtigungen werden dem Site-Administrator bei der Installation angezeigt, in sieben Gruppen mit einer Ein-Satz-Begründung pro Gruppe. Siehe Berechtigungsreferenz.

Block-Markup rendern

Beiträge und Seiten, die von der Bridge zurückgegeben werden, enthalten den Inhalt als block-formatiertes HTML in post.content. Das Einfügen in das DOM gibt Ihnen das Markup, aber nicht die Stile, die WordPress im Frontend erzeugen würde (Cover hat keine min-height, Columns sind nicht flex, etc.). Aktivieren Sie dies im Manifest, rufen Sie dann den SDK-Helper nach dem Rendering auf:

"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

Füge "designsetgo" für Partner-Plugin-Stile hinzu, oder "themeStyles": "global" um das kompilierte Theme zu versenden theme.json CSS des Themes auszuliefern. Die kombinierte Nutzlast ist auf 256 KB pro Beitrag begrenzt.

Dynamische Routen aus Live-Daten

Für Inhalte, die der WordPress-Editor besitzt (Beiträge, Produkte, benutzerdefinierte Post-Typen), versenden Sie nicht eine Astro-Seite pro Element; deklarieren Sie stattdessen eine einzelne Template-Route mit ein :param Platzhalter und verweise auf einen Live-Datensatz. Das Plugin löst die Route zur Anfragezeit auf und ersetzt Felder im Template.

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

Das Template unter src/pages/post.astro verwendet {{title}}, {{excerpt}}, {{content}} Platzhalter (serverseitig ersetzt) oder, für reichhaltigeres Rendering, ruft die Bridge mit dsgo.context.routeParams.slug auf, um das vollständige Beitragsobjekt abzurufen.

Live-Quellen sind eine Pro. Funktion. Mit Free wird die App installiert und statische Routen werden weiterhin bereitgestellt; Live-Quell-Routen bleiben inaktiv, bis Pro aktiv ist. Ergebnisse werden pro App+Route+Version eine Stunde lang zwischengespeichert; Speichern und Löschen des zugrundeliegenden Beitragstyps invalidieren automatisch.

@designsetgo/astro: Vertical-Pack-Komponenten

Wenn du ein WooCommerce-Frontend baust (und später: Immobilien, Fitness, Lebensmittel, lokale Dienste), @designsetgo/astro ist ein separates npm-Paket mit vorgefertigten Astro-Komponenten für jeden DSGo vertical pack, plus eine kleine Astro-Integration, die die erforderlichen Berechtigungen, Fähigkeiten und Commerce-Endpunkte der Komponenten automatisch in Ihrem zusammenführt dsgo-app.json beim Build zusammenführt. v0.1.0 enthält 14 WooCommerce-Komponenten.

Nützlich, wenn du das Projekt mit Claude Code, Cursor oder Codex vibe-codest: Wenn die KI Komponentenimporte hinzufügt und entfernt, hält die Integration dsgo-app.json ehrlich. Der CI-Build schlägt fehl, wenn Ihr Manifest von dem abweicht, was die Importe tatsächlich benötigen.

Paket installieren

npm install @designsetgo/astro

Astro 4 oder 5 ist eine Peer-Abhängigkeit, die du bereits hast. Der Bridge-Client ( @designsetgo/app-client) ist ein optionaler Peer; Komponenten importieren ihn transitiv, du benötigst ihn also nur für eigene <script> Blöcke.

Integration hinzufügen

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

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

Eine Zeile in astro.config.mjs. Bei jedem Build durchsucht die Integration dein Projekt nach @designsetgo/astro/<pack> Importe, lädt das Manifest jeder Komponente von node_modules, vereinigt die erforderlichen Berechtigungen in deinem dsgo-app.json (alle anderen Schlüssel bleiben erhalten), und gibt ein .astro/dsgo-window.d.ts Shim aus, sodass window.dsgo die Autovervollständigung gegen die tatsächlich deklarierten Berechtigungen arbeitet.

Komponente importieren

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

Jede Komponente rendert ihr eigenes Markup, liefert ihr eigenes Scoped-CSS und startet ein kleines Client-Bundle innerhalb eines IIFE, das auf sein data-dsgo-component Slug. Zwei Komponenten auf der gleichen Seite sind slug-isoliert; Bundle A's mount wird nie für Bundle B's Roots ausgelöst.

Komponentenkatalog (v0.1.0)

WooCommerce-Pack ( @designsetgo/astro/woo):

Jede Komponente ist verhaltenserhaltend gegenüber ihrem Standalone-Bundle-Gegenstück in examples/woo-*/; ein Paritätstest und ein Pre-Commit-Hook halten sie synchron. Der vollständige Katalog mit Beschreibungen, Optionen und Fehlerbehebung befindet sich im Paket-README.

Schreib- vs. Prüfmodus

mode: 'write' (Standard) schreibt dsgo-app.json an Ort und Stelle neu, wenn eine importierte Komponente Berechtigungen hinzufügt. mode: 'check' beendet den Build mit einem Nicht-Null-Exit-Code und einem gedruckten Diff, wenn die Datei veraltet ist. Verwende 'check' in CI, damit ein vergessenes Manifest-Restaging den Build unterbricht:

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

Das Zusammenführen ist nur additiv; die Integration entfernt niemals Berechtigungen. Der lokale Entwicklungsmodus verzögert Zusammenführungen um 200ms, damit das Speichern einer Datei, die einen Import hinzufügt, das Manifest nicht überlastet.

Präfixierter Mount (Standard)

Ohne einen mount Block wird die App unter /apps/<id>/.... Gut geeignet zum Hinzufügen eines Tools, einer Microsite oder einer Marketing-Oberfläche neben einer vorhandenen WP-Website, ohne zu ändern, was sich auf befindet. /.

Root-Mount (gesamte Site)

Um die Astro-App zur Site zu machen, füge dem Manifest hinzu:

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

Die App wird jetzt unter /. Die von Ihnen deklarierten Astro-Routes besitzen die URLs, die WordPress sonst servieren würde; jeder Pfad, auf dem WP eine 404 zurückgeben würde, fällt durch die Route-Tabelle. Echte WP-Seiten, Beiträge, Archive und Feeds gewinnen standardmäßig; Root-Modus fügt hinzu, es wird nicht überschattet; so kann der Redakteur weiterhin in wp-admin veröffentlichen.

Wenn eine Astro-Route WP absichtlich überschreiben muss (z.B. eine app-gerenderte /blog gestützt durch wp:posts das sonst mit WP's nativem Blog-Archiv kollidieren würde), fügen Sie hinzu claim: "always" zu dieser Route hinzu. Siehe Routen beanspruchen.

Bauen und deployen

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

--build führt npm run build zuerst aus. Die CLI zippt dann dist/, validiert das Manifest, zeigt den Capability-Unterschied und sendet das Bundle an den REST-Endpunkt der Website. Erneutes Ausführen deploy aktualisiert die bestehende Installation atomar mit derselben App-ID.

Mit Free apps init --astro und lokale Builds funktionieren; deploy fällt auf einen wp-admin Bundle-Upload zurück (Pfad B). Mit Pro kannst du direkt vom Terminal aus deployen.

Caching

• Statische Assets invalidieren sich selbst. Astro + Vite erzeugen inhaltsgehashte Dateinamen ( app.BYFSNV21.css). Ein neuer Build = ein neuer Hash = automatische Edge-Cache-Invalidierung. Sicher auf max-age ein Jahr setzen.
• HTML-Routen sind öffentlich cachebar für anonyme Besucher. Benutzerspezifische Daten fließen zur Laufzeit über die Bridge, nicht über das SSR-HTML.
• Bridge-Aufrufe ( /wp-json/dsgo/v1/*) dürfen nicht gecacht werden. Die Bridge sendet Cache-Control: no-store; überschreiben Sie es nicht mit einer CDN-Regel "Cache Everything".
• Root-Mount-Asset-URLs werden umgeschrieben zu /wp-content/uploads/designsetgo-apps/<id>/... damit nginx sie direkt ausliefert, ohne PHP zu durchlaufen.

Vollständige Anleitung: Caching & CDNs in der Hauptdokumentation.

Häufige Fallstricke

Inline-Skripte beim Deployment abgelehnt

Der CSP-Sanitizer lehnt inline <script> Inhalte ab. Setze vite.build.assetsInlineLimit: 0 in astro.config.mjs , damit Vite Skripte als externe Dateien ausgibt. Für Drittanbieter-Origins füge den Host zu runtime.csp.script_src.

Seite gibt nach dem Deployment 404 zurück

Jede URL muss in routes. Der file Pfad ist bundle-relativ ( dist/ Root); mit format: 'directory', src/pages/about.astro zugeordnet zu about/index.html, nicht about.html.

Root-Mount-Asset-404-Fehler

Bei verwalteten Hosts (GoDaddy MWP, WP Engine) kann nginx .css/.js/.svg Anfragen vor WordPress abfangen. Erfordert DSGo Apps 0.1.1+, das Bundle-Asset-URLs zum tatsächlichen Upload-Pfad umschreibt. Upgrade durchführen, dann neu deployen. Siehe Fehlerbehebung.

dsgo-app.json fehlt im Bundle

Das Manifest muss sich innerhalb von dist/ wenn die CLI es zipped. Legen Sie es in Astro's public/ Ordner ab, oder kopiere es nach dem Build: "build": "astro build && cp dsgo-app.json dist/".

Links brechen beim Wechsel zum Root-Mount

Hart kodierte /apps/<id>/ hrefs werden nicht aufgelöst unter /. Verlinke immer über ${import.meta.env.BASE_URL}path damit beide Mount-Modi ohne Code-Änderungen funktionieren.

Nächste Schritte

• Vollständige Bridge API — jede Methode, jeder Fehlercode und jeder Berechtigungsbereich
• Manifest-Referenz — das vollständige dsgo-app.json Schema
• CLI-Befehle — init, deploy, doctor, Multi-Site-Flags
• Berechtigungen — der Sieben-Gruppen-Installationsdialog und was jede Berechtigung gewährt
• Die narrative Version — gleicher Workflow, als Schritt-für-Schritt-Anleitung

Etwas fehlt oder ist unklar? Schreiben Sie uns.