Build an Astro site on WordPress.

Prérequis

• Node 20+ et un terminal.
• Un site WordPress (6.9+) avec le DesignSetGo Apps plugin activé.
• Un Mot de passe d’application WordPress pour ce site.

Free couvre 1 application statique active. Routes dynamiques en direct ( wp:posts, wc:products, etc.), les applications actives illimitées et le déploiement CLI nécessitent Pro.

Initialiser le projet

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

Le starter Astro inclut un astro.config.mjs déjà connecté au manifeste DSGo, un Layout.astrode base, trois pages d’exemple, un CLAUDE.md documentant le bridge pour les agents, et un dsgo-app.json avec la route d’accueil pré-déclarée.

astro.config.mjs

Astro a besoin de trois choses pour produire un bundle que DSGo peut servir : un base correspondant à l’URL où le plugin monte l’application, une sortie statique et des routes au format répertoire pour que chaque page s’émette en tant que 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 — lit le manifeste afin que basculer mount.mode entre "prefixed" et "root" ne nécessite pas de modifier la configuration. Astro réécrit les URLs des ressources internes en conséquence.
• build.format: 'directory' — src/pages/about.astro émet vers dist/about/index.html, ce que le champ file du manifeste référence.
• vite.build.assetsInlineLimit: 0 — empêche Vite d’inliner les petites ressources en tant que <script> corps, que le nettoyeur CSP de DSGo rejette.

Le manifeste

Chaque page produite par Astro doit être déclarée dans dsgo-app.json sous routes. Le file chemin est relatif au bundle (relatif à dist/), donc une page Astro à src/pages/pricing.astro avec format: 'directory' correspond à 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": [] }
}

Assurez-vous que le manifeste se retrouve à l’intérieur du bundle que le CLI téléverse. Le chemin le plus simple est de le déposer dans le dossier public/ d’Astro (il est copié tel quel dans dist/), ou demandez au script de build de le copier : "build": "astro build && cp dsgo-app.json dist/".

routes[0] doit avoir path: "/". La route d’accueil est obligatoire.

Ajouter des pages

Rédigez des pages Astro comme vous le feriez normalement. Il n’y a pas de plugin de build DSGo, pas de composant spécial, pas de getStaticPaths contrat requis — seulement Astro.

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

Ajoutez l’entrée correspondante sous routes dans le manifeste et la page se résoudra au chemin de base configuré.

Liens entre les pages

Astro ne réécrit pas les valeurs href , seulement les URLs des ressources. Pour les liens internes, utilisez import.meta.env.BASE_URL pour que les montages préfixé et racine fonctionnent tous les deux sans modifications du code :

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

Pour la navigation programmatique à l’intérieur de l’application, préférez dsgo.router.navigate(path) — le parent valide que le nouveau chemin reste à l’intérieur du montage de l’application et met à jour l’URL du navigateur en toute sécurité. Les appels directs history.pushState en dehors du montage sont bloqués.

Lire les données WordPress

Importez @designsetgo/app-client dans n’importe quelle page ou composant Astro <script>. Le bridge s’exécute dans le navigateur au moment de la consultation, de sorte que la page elle-même reste une ressource statique que les robots d’indexation peuvent analyser.

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

La surface complète du bridge (articles, pages, utilisateur, médias, IA, commerce, stockage, abilities, e-mail, HTTP, routeur) est documentée dans la référence du bridge.

Déclarer les permissions

Les méthodes du bridge sont conditionnées par ce que le manifeste déclare. Ajoutez la permission requise par l’appel avant de déployer, sinon l’installation sera rejetée lors du précontrôle.

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

Les permissions sont présentées à l’administrateur du site lors de l’installation, regroupées en sept catégories avec une justification d’une phrase par catégorie. Voir référence des permissions.

Afficher le balisage de blocs

Les articles et pages retournés par le bridge incluent le corps en HTML formaté en blocs via post.content. L’injecter dans le DOM vous donne le balisage mais pas les styles que WordPress émettrait sur son front-end (Cover n’a pas de min-height, Columns n’est pas flex, etc.). Activez-le via le manifeste, puis appelez l’assistant SDK après le rendu :

"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

Ajoutez "designsetgo" pour les styles des plugins partenaires, ou "themeStyles": "global" pour livrer le fichier theme.json CSS compilé du thème. La charge utile combinée est limitée à 256 Ko par article.

Routes dynamiques depuis les données en direct

Pour le contenu géré par l’éditeur WordPress (articles, produits, types de contenu personnalisés), ne livrez pas une page Astro par élément — déclarez une seule route de modèle avec un :param espace réservé et pointez-le vers un jeu de données en direct. Le plugin le résout au moment de la requête et substitue les champs dans le modèle.

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

Le modèle à src/pages/post.astro utilise des {{title}}, {{excerpt}}, {{content}} espaces réservés (substitués côté serveur) ou, pour un rendu plus riche, appelle le bridge avec dsgo.context.routeParams.slug pour récupérer l’objet article complet.

Les sources en direct sont Pro. Sur Free, l’application s’installe et les routes statiques fonctionnent toujours ; les routes depuis sources en direct restent inactives jusqu’à l’activation de Pro. Les résultats sont mis en cache par application+route+version pendant une heure ; les sauvegardes et suppressions sur le type de contenu sous-jacent invalident automatiquement le cache.

@designsetgo/astro : composants de pack vertical

Si vous créez un front-end WooCommerce (et ultérieurement : immobilier, fitness, restauration, services locaux), @designsetgo/astro est un package npm séparé avec des composants Astro préconstruits pour chaque pack vertical DSGo, plus une petite intégration Astro qui fusionne automatiquement les permissions, abilities et points de terminaison commerce requis par les composants dans votre dsgo-app.json au moment du build. v0.1.0 inclut 14 composants WooCommerce.

Utile si vous vibe-code le projet avec Claude Code, Cursor ou Codex : lorsque l’IA ajoute et supprime des imports de composants, l’intégration maintient dsgo-app.json cohérent. Le build CI échoue si votre manifeste diverge de ce que les imports nécessitent réellement.

Installer le package

npm install @designsetgo/astro

Astro 4 ou 5 est une dépendance homologue que vous avez déjà. Le client bridge ( @designsetgo/app-client) est un homologue optionnel ; les composants l’importent de manière transitive, vous n’en avez donc besoin que pour vos propres blocs <script> .

Ajouter l’intégration

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

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

Une ligne dans astro.config.mjs. À chaque build, l’intégration analyse votre projet à la recherche d’imports @designsetgo/astro/<pack> , charge le manifeste de chaque composant depuis node_modules, fusionne ses permissions requises dans votre dsgo-app.json (en préservant toutes les autres clés), et émet un .astro/dsgo-window.d.ts shim afin que window.dsgo s’auto-complète selon les permissions que vous avez réellement déclarées.

Importer un composant

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

Chaque composant affiche son propre balisage, inclut son propre CSS scopé et s’initialise avec un petit bundle client dans une IIFE associée à son data-dsgo-component slug. Deux composants sur la même page sont isolés par slug ; l’événement mount du bundle A ne se déclenchera jamais pour les racines du bundle B.

Catalogue de composants (v0.1.0)

Pack WooCommerce ( @designsetgo/astro/woo) :

Chaque composant est équivalent en comportement à son homologue en bundle autonome dans examples/woo-*/; un test de parité et un hook pre-commit les maintiennent synchronisés. Le catalogue complet avec descriptions, options et dépannage se trouve dans le README du package.

Mode écriture vs vérification

mode: 'write' (par défaut) réécrit dsgo-app.json en place lorsqu’un composant importé ajoute des permissions. mode: 'check' termine le build avec un code non nul et un diff imprimé si le fichier est obsolète. Utilisez 'check' en CI afin qu’un re-staging de manifeste oublié interrompe le build :

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

La fusion est uniquement additive ; l’intégration ne supprime jamais de permissions. Le mode dev local anti-rebondit les fusions de 200ms afin que la sauvegarde d’un fichier ajoutant un import ne surcharge pas le manifeste.

Montage préfixé (par défaut)

Sans bloc mount , l’application est servie à /apps/<id>/.... Idéal pour ajouter un outil, un microsite ou une surface marketing à côté d’un site WP existant sans modifier ce qui se trouve à /.

Montage racine (site entier)

Pour que l’application Astro soit le site, ajoutez au manifeste :

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

L’application est désormais servie à /. Les routes Astro que vous avez déclarées possèdent les URLs que WordPress servirait autrement ; tout chemin sur lequel WP aurait renvoyé une 404 transite vers la table de routage. Les pages, articles, archives et flux WP réels gagnent toujours par défaut — le mode racine ajoute, il ne masque pas — ainsi l’éditeur peut continuer à publier dans wp-admin.

Si une route Astro doit délibérément remplacer WP (par ex. un /blog rendu par l’application, soutenu par wp:posts qui entrerait autrement en conflit avec l’archive de blog native de WP), ajoutez claim: "always" à cette route. Voir revendiquer des routes.

Compilation et déploiement

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

--build exécute npm run build d’abord. Le CLI compresse ensuite dist/, valide le manifeste, affiche le diff des capacités et envoie le bundle au point de terminaison REST du site. Relancer deploy met à jour l’installation existante de manière atomique au même identifiant d’application.

Sur Free, apps init --astro et les builds locaux fonctionnent ; deploy se replie sur un téléversement de bundle wp-admin (Chemin B). Sur Pro, déployez directement depuis le terminal.

Mise en cache

• Les ressources statiques s’auto-invalident. Astro + Vite émettent des noms de fichiers hachés par contenu ( app.BYFSNV21.css). Un nouveau build = un nouveau hachage = invalidation automatique du cache edge. Sûr de définir max-age à un an.
• Les routes HTML sont publiquement mettables en cache pour les visiteurs anonymes. Les données par utilisateur transitent par le bridge à l’exécution, pas dans le HTML rendu côté serveur.
• Les appels du bridge ( /wp-json/dsgo/v1/*) ne doivent pas être mis en cache. Le bridge envoie Cache-Control: no-store; ne le remplacez pas avec une règle CDN « Tout mettre en cache ».
• URLs des ressources en montage racine sont réécrites vers /wp-content/uploads/designsetgo-apps/<id>/... afin que nginx les serve directement, en contournant PHP.

Directives complètes : mise en cache & CDN dans la documentation principale.

Pièges courants

Scripts inline rejetés au déploiement

Le nettoyeur CSP rejette les corps <script> inline. Définissez vite.build.assetsInlineLimit: 0 dans astro.config.mjs afin que Vite émette les scripts en tant que fichiers externes. Pour les origines tierces, ajoutez l’hôte à runtime.csp.script_src.

La page renvoie une 404 après déploiement

Chaque URL doit être déclarée dans routes. Le file chemin est relatif au bundle ( dist/ racine) ; avec format: 'directory', src/pages/about.astro correspond à about/index.html, pas about.html.

Erreurs 404 des ressources en montage racine

Sur les hébergements gérés (GoDaddy MWP, WP Engine), nginx peut traiter rapidement les requêtes .css/.js/.svg avant l’exécution de WordPress. Nécessite DSGo Apps 0.1.1+, qui réécrit les URLs des ressources du bundle vers le chemin de téléversement réel. Mettez à niveau, puis redéployez. Voir dépannage.

dsgo-app.json absent du bundle

Le manifeste doit se trouver à l’intérieur de dist/ lorsque le CLI le compresse. Déposez-le dans le dossier public/ d’Astro, ou copiez-le après le build : "build": "astro build && cp dsgo-app.json dist/".

Les liens se cassent lors du passage au montage racine

Les /apps/<id>/ hrefs codés en dur ne se résoudront pas à /. Créez toujours des liens via ${import.meta.env.BASE_URL}path afin que les deux modes de montage fonctionnent sans modification de code.

Où aller ensuite

• API bridge complète — chaque méthode, code d'erreur et portée de permission
• Référence du manifeste — le schéma complet dsgo-app.json schéma
• Commandes CLI — init, deploy, doctor, options multi-sites
• Permissions — la boîte de dialogue d'installation à sept catégories et ce que chaque permission accorde
• La version narrative — même flux de travail, sous forme de guide pas à pas

Quelque chose manque ou n'est pas clair ? Contactez-nous par e-mail.