Build an Astro site on WordPress.

Requisitos previos

• Node 20+ y un terminal.
• Un sitio WordPress (6.9+) con el plugin DesignSetGo Apps activado.
• Una Contrasena de aplicacion de WordPress para ese sitio.

Gratuito cubre 1 aplicación estática activa. Rutas dinámicas de origen en vivo ( wp:posts, wc:products, etc.), aplicaciones activas ilimitadas e implementación de CLI requieren Pro.

Scaffold del proyecto

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

El starter de Astro incluye un astro.config.mjs ya conectado al manifiesto de DSGo, una Layout.astrode base, tres paginas de ejemplo, un CLAUDE.md que documenta el bridge para agentes y un dsgo-app.json con la ruta de inicio predeclarada.

astro.config.mjs

Astro necesita tres cosas para producir un bundle que DSGo pueda servir: una base que coincida con la URL donde el plugin monta la app, salida estatica y rutas en formato directorio para que cada pagina emita como 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 — lee el manifiesto para que cambiar mount.mode entre "prefixed" y "root" no requiera editar la configuracion. Astro reescribe las URLs de assets internos para que coincidan.
• build.format: 'directory' — src/pages/about.astro emite en dist/about/index.html, que es lo que referencia el campo file del manifiesto.
• vite.build.assetsInlineLimit: 0 — evita que Vite incluya assets pequenos como cuerpos <script> , que el sanitizador de CSP de DSGo rechaza.

El manifiesto

Cada pagina que produce Astro debe declararse en dsgo-app.json bajo routes. La ruta file es relativa al bundle (relativa a dist/), de modo que una pagina Astro en src/pages/pricing.astro con format: 'directory' se mapea a 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": [] }
}

Asegurate de que el manifiesto quede dentro del bundle que sube el CLI. La forma mas sencilla es colocarlo en la carpeta public/ de Astro (se copia textualmente en dist/), o hacer que el script de compilacion lo copie: "build": "astro build && cp dsgo-app.json dist/".

routes[0] debe tener path: "/". La ruta de inicio es obligatoria.

Agregar paginas

Escribe paginas Astro como lo harias normalmente. No hay plugin de compilacion de DSGo, ni componente especial, ni contrato getStaticPaths requerido; solo Astro.

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

Agrega la entrada correspondiente bajo routes en el manifiesto y la pagina se resolvera en la ruta base configurada.

Enlazar entre paginas

Astro no reescribe los valores href , solo las URLs de assets. Para los enlaces internos usa import.meta.env.BASE_URL para que tanto el montaje con prefijo como el montaje en raiz funcionen sin cambios de codigo:

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

Para la navegacion programatica dentro de la app, prefiere dsgo.router.navigate(path) — el padre valida que la nueva ruta permanezca dentro del montaje de la app y actualiza la URL del navegador de forma segura. Las llamadas directas a history.pushState fuera del montaje estan bloqueadas.

Leer datos de WordPress

Importa @designsetgo/app-client en cualquier pagina o componente Astro <script>. El bridge se ejecuta en el navegador en el momento de la vista, de modo que la pagina en si permanece como un asset estatico que los rastreadores pueden indexar.

---
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 superficie completa del bridge (publicaciones, paginas, usuario, multimedia, IA, comercio, almacenamiento, abilities, email, HTTP, router) esta documentada en la referencia del bridge.

Declarar permisos

Los metodos del bridge estan controlados por lo que declara el manifiesto. Agrega el permiso que necesita la llamada antes de desplegar o la instalacion sera rechazada en el preflight.

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

Los permisos se muestran al administrador del sitio en el momento de la instalacion, agrupados en siete buckets con una justificacion de una frase por bucket. Consulta la referencia de permisos.

Renderizar markup de bloques

Las publicaciones y paginas devueltas por el bridge incluyen el cuerpo como HTML formateado con bloques en post.content. Insertarlo en el DOM te da el markup pero no los estilos que WordPress emitira en su frontend (Cover no tiene min-height, Columns no son flex, etc.). Activa esto en el manifiesto y luego llama al helper del SDK despues de renderizar:

"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

Agrega "designsetgo" para los estilos de plugins asociados, o "themeStyles": "global" para incluir el theme.json CSS compilado del tema. El payload combinado tiene un limite de 256 KB por publicacion.

Rutas dinamicas desde datos en vivo

Para contenido que gestiona el editor de WordPress (publicaciones, productos, tipos de publicacion personalizados), no distribuyas una pagina Astro por elemento; declara una ruta de plantilla unica con un marcador de posicion :param y apuntala a un conjunto de datos en vivo. El plugin lo resuelve en el momento de la solicitud y sustituye los campos en la plantilla.

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

La plantilla en src/pages/post.astro usa marcadores de posicion {{title}}, {{excerpt}}, {{content}} (sustituidos en el servidor) o, para un renderizado mas rico, llama al bridge con dsgo.context.routeParams.slug para obtener el objeto completo de la publicacion.

Las fuentes en vivo son una funcion Pro. En el plan gratuito, la app se instala y las rutas estaticas siguen funcionando; las rutas con fuente en vivo permanecen inactivas hasta que Pro este activo. Los resultados se almacenan en cache por app+ruta+version durante una hora; las guardadas y eliminaciones en el tipo de publicacion subyacente invalidan la cache automaticamente.

@designsetgo/astro: componentes del pack vertical

Si estas construyendo un frontend de WooCommerce (y mas adelante: inmobiliaria, fitness, alimentacion, servicios locales), @designsetgo/astro es un paquete npm separado con componentes Astro preconstruidos para cada pack vertical de DSGo, ademas de una pequena integracion Astro que fusiona automaticamente los permisos, abilities y endpoints de comercio requeridos por los componentes en tu dsgo-app.json en tiempo de compilacion. v0.1.0 incluye 14 componentes de WooCommerce.

Util si estas vibe-coding el proyecto con Claude Code, Cursor o Codex: a medida que la IA agrega y elimina importaciones de componentes, la integracion mantiene dsgo-app.json actualizado. La compilacion de CI falla si tu manifiesto se desvio de lo que las importaciones realmente necesitan.

Instalar el paquete

npm install @designsetgo/astro

Astro 4 o 5 es una dependencia de pares que ya tienes. El cliente bridge ( @designsetgo/app-client) es una dependencia de pares opcional; los componentes lo importan transitivamente, por lo que solo lo necesitas para tus propios bloques <script> .

Agregar la integracion

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

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

Una linea en astro.config.mjs. En cada compilacion la integracion escanea tu proyecto en busca de importaciones de @designsetgo/astro/<pack> , carga el manifiesto de cada componente desde node_modules, une sus permisos requeridos en tu dsgo-app.json (conservando todas las demas claves) y emite un shim .astro/dsgo-window.d.ts para que window.dsgo autocomplete contra los permisos que realmente declaraste.

Importar un componente

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

Cada componente renderiza su propio markup, incluye su propio CSS con alcance limitado y arranca un pequeno bundle cliente dentro de un IIFE con clave en su slug data-dsgo-component . Dos componentes en la misma pagina estan aislados por slug; el mount del bundle A nunca disparara para las raices del bundle B.

Catalogo de componentes (v0.1.0)

Pack WooCommerce ( @designsetgo/astro/woo):

Cada componente preserva el comportamiento con su contraparte de bundle independiente en examples/woo-*/; una prueba de paridad y un pre-commit hook los mantienen sincronizados. El catalogo completo con descripciones, opciones y solucion de problemas esta en el README del paquete.

Modo write vs check

mode: 'write' (predeterminado) reescribe dsgo-app.json en el lugar cuando un componente importado agrega permisos. mode: 'check' termina la compilacion con codigo no cero con un diff impreso si el archivo esta desactualizado. Usa 'check' en CI para que un manifiesto olvidado rompa la compilacion:

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

La fusion es solo aditiva; la integracion nunca elimina permisos. El modo de desarrollo local elimina el rebote de fusiones a 200ms para que guardar un archivo que agrega una importacion no sacuda el manifiesto.

Montaje con prefijo (predeterminado)

Sin un bloque mount , la app se sirve en /apps/<id>/.... Ideal para agregar una herramienta, micrositio o superficie de marketing junto a un sitio WP existente sin cambiar lo que hay en /.

Montaje en raiz (sitio completo)

Para que la app Astro sea el sitio, agrega al manifiesto:

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

La app ahora se sirve en /. Las rutas Astro que declaraste son las duenas de las URLs que WordPress serviria de otro modo; cualquier ruta en la que WP habria devuelto 404 pasa a la tabla de rutas. Las paginas, publicaciones, archivos y feeds reales de WP siguen ganando por defecto; el modo raiz agrega, no sombrea; asi el editor puede seguir publicando en wp-admin.

Si una ruta Astro necesita deliberadamente sobreescribir WP (p. ej., un /blog renderizado por la app respaldado por wp:posts que de otro modo colisionaria con el archivo de blog nativo de WP), agrega claim: "always" a esa ruta. Consulta reclamar rutas.

Compilar y desplegar

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

--build ejecuta npm run build primero. El CLI luego comprime dist/, valida el manifiesto, muestra la diferencia de capacidades y sube el bundle al endpoint REST del sitio. Volver a ejecutar deploy actualiza la instalacion existente atomicamente con el mismo id de app.

En el plan gratuito, apps init --astro y las compilaciones locales funcionan; deploy recurre a la subida del bundle en wp-admin (Ruta B). En Pro, despliega desde el terminal directamente.

Cacheo

• Los assets estaticos se invalidan solos. Astro + Vite emiten nombres de archivo con hash de contenido ( app.BYFSNV21.css). Una nueva compilacion = un nuevo hash = invalidacion automatica de la cache de borde. Seguro para fijar max-age en un ano.
• Las rutas HTML son cacheable publicamente para visitantes anonimos. Los datos por usuario fluyen a traves del bridge en tiempo de ejecucion, no del HTML renderizado en el servidor.
• Las llamadas al bridge ( /wp-json/dsgo/v1/*) no deben cachearse. El bridge envia Cache-Control: no-store; no lo sobreescribas con una regla "Cache Everything" de CDN.
• Las URLs de assets en el montaje raiz se reescriben a /wp-content/uploads/designsetgo-apps/<id>/... para que nginx los sirva directamente, sin pasar por PHP.

Orientacion completa: cacheo y CDNs en la documentacion principal.

Errores comunes

Scripts en linea rechazados al desplegar

El sanitizador de CSP rechaza cuerpos <script> en linea. Define vite.build.assetsInlineLimit: 0 en astro.config.mjs para que Vite emita los scripts como archivos externos. Para origenes de terceros, agrega el host a runtime.csp.script_src.

La pagina devuelve 404 despues de desplegar

Cada URL debe declararse en routes. La ruta file es relativa al bundle ( dist/ raiz); con format: 'directory', src/pages/about.astro se mapea a about/index.html, no about.html.

Assets 404 en montaje raiz

En hosts gestionados (GoDaddy MWP, WP Engine), nginx puede adelantarse a las solicitudes que terminan con extensiones estaticas conocidas ( .css/.js/.svg antes de que WordPress se ejecute. Requiere DSGo Apps 0.1.1+, que reescribe las URLs de assets del bundle a la ruta de subida real. Actualiza y vuelve a desplegar. Consulta solucion de problemas.

dsgo-app.json ausente del bundle

El manifiesto debe estar dentro de dist/ cuando el CLI lo comprime. Coloca en la carpeta public/ de Astro, o copialo despues de la compilacion: "build": "astro build && cp dsgo-app.json dist/".

Los enlaces se rompen al cambiar al montaje raiz

Los hrefs /apps/<id>/ de codigo fijo no se resolveran en /. Enlaza siempre usando ${import.meta.env.BASE_URL}path para que ambos modos de montaje funcionen sin cambios de codigo.

Donde ir despues

• Bridge API completa — cada metodo, codigo de error y alcance de permiso
• Referencia del manifiesto — el esquema dsgo-app.json completo
• Comandos del CLI — init, deploy, doctor, flags multi-sitio
• Permisos — el dialogo de instalacion de siete buckets y lo que otorga cada permiso
• La version narrativa — el mismo flujo de trabajo, en forma de tutorial

¿Falta algo o no esta claro? Envíanos un correo.