Build an Astro site on WordPress.

Pré-requisitos

• Node 20+ e um terminal.
• Um site WordPress (6.9+) com o plugin DesignSetGo Apps ativado.
• Uma Senha de Aplicativo do WordPress para esse site.

Gratuito cobre 1 aplicativo estático ativo. Rotas dinâmicas de fonte ao vivo ( wp:posts, wc:products, etc.), aplicativos ativos ilimitados e CLI deploy exigem Pro.

Criar estrutura do projeto

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

O starter Astro inclui um astro.config.mjs já conectado ao manifest DSGo, uma base Layout.astro, três páginas de exemplo, um CLAUDE.md documentando o bridge para agentes, e um dsgo-app.json com a rota principal pré-declarada.

astro.config.mjs

O Astro precisa de três coisas para gerar um bundle que o DSGo consiga servir: um base correspondente à URL em que o plugin monta o app, saída estática e rotas no formato de diretório para que cada página seja emitida 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 — lê o manifest para que alternar mount.mode entre "prefixed" e "root" não requer edição de configuração. Astro reescreve URLs de ativos internos para corresponder.
• build.format: 'directory' — src/pages/about.astro emite em dist/about/index.html, que é o que do manifest file do manifest referencia.
• vite.build.assetsInlineLimit: 0 — impede o Vite de embutir assets pequenos como <script> bodies, que o sanitizador CSP do DSGo rejeita.

O manifest

Toda página que o Astro produz deve ser declarada em dsgo-app.json sob routes. O file caminho é relativo ao bundle (relativo a dist/), portanto uma página Astro em src/pages/pricing.astro com format: 'directory' mapeia para 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": [] }
}

Certifique-se de que o manifest esteja dentro o pacote que o CLI faz upload. O caminho mais fácil é soltá-lo no Astro public/ pasta (é copiada verbatim para dist/), ou fazer o script de build copiá-lo: "build": "astro build && cp dsgo-app.json dist/".

routes[0] deve ter path: "/". A rota principal é obrigatória.

Adicionar páginas

Escreva páginas Astro como você normalmente faria. Não há plugin de build DSGo, nenhum componente especial, nada necessário getStaticPaths contrato obrigatório, apenas Astro.

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

Adicione a entrada correspondente sob routes no manifest e a página será resolvida no base path configurado.

Links entre páginas

Astro não reescreve href , apenas URLs de assets. Para links internos, use import.meta.env.BASE_URL para que montagens com prefixo e na raiz funcionem sem alterações no código:

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

Para navegação programática dentro do app, prefira dsgo.router.navigate(path) — o parent valida que o novo caminho permanece dentro da montagem do app e atualiza a URL do navegador de forma segura. Chamadas diretas de history.pushState fora da montagem são bloqueadas.

Ler dados do WordPress

Importe @designsetgo/app-client em qualquer página ou componente Astro <script>. O bridge é executado no navegador no momento da visualização, portanto a própria página permanece um asset estático que os crawlers podem 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>

A superfície completa do bridge (posts, pages, user, media, IA, commerce, storage, abilities, email, HTTP, router) está documentada em a referência do bridge.

Declarar permissões

Os métodos do bridge são controlados pelo que o manifest declara. Adicione a permissão necessária para a chamada antes de fazer o deploy, ou a instalação será rejeitada no preflight.

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

As permissões são exibidas ao administrador do site no momento da instalação, agrupadas em sete categorias com uma justificativa de uma frase por categoria. Consulte referência de permissões.

Renderizar marcação de bloco

Posts e páginas retornados pelo bridge incluem o corpo como HTML formatado em blocos em post.content. Soltando-o no DOM, você obtém a marcação mas não os estilos que WordPress emitiria no front-end (Cover não tem min-height, Columns não são flex, etc.). Ative via manifest, depois chame o auxiliar SDK após 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

Adicione "designsetgo" para estilos de plugins parceiros, ou "themeStyles": "global" para enviar o compilado do tema theme.json CSS compilado do tema. O payload combinado é limitado a 256 KB por post.

Rotas dinâmicas com dados reais

Para conteúdo que o editor WordPress possui (posts, produtos, tipos de post customizados), não envie uma página Astro por item; declare uma rota de template única com um :param placeholder e aponte para um dataset ao vivo. O plugin resolve no momento da requisição e substitui os campos no template.

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

O template em src/pages/post.astro usa {{title}}, {{excerpt}}, {{content}} placeholders (substituídos pelo servidor) ou, para renderização mais rica, chama o bridge com dsgo.context.routeParams.slug para buscar o objeto completo do post.

Fontes ao vivo são um recurso Pro. No plano Free, o app instala e as rotas estáticas continuam funcionando; as rotas com fonte ao vivo permanecem inativas até o Pro estar ativo. Os resultados são armazenados em cache por app+rota+versão durante uma hora; salvamentos e exclusões no post type subjacente invalidam automaticamente.

@designsetgo/astro: componentes de pacote vertical

Se você está criando um front-end para WooCommerce (e futuramente: imóveis, fitness, alimentação, serviços locais), @designsetgo/astro é um pacote npm separado com componentes Astro pré-construídos para cada pacote vertical DSGo, além de uma pequena integração Astro que mescla automaticamente as permissões requeridas dos componentes, habilidades e endpoints de comércio em seu dsgo-app.json em tempo de build. A v0.1.0 inclui 14 componentes WooCommerce.

Útil se você está vibe-coding o projeto com Claude Code, Cursor ou Codex: conforme a IA adiciona e remove importações de componentes, a integração mantém o dsgo-app.json honesto. O build do CI falha se seu manifest se afasta do que os imports realmente precisam.

Instalar o pacote

npm install @designsetgo/astro

Astro 4 ou 5 é uma peer dependency que você já tem. O bridge client ( @designsetgo/app-client) é um peer opcional; os componentes o importam transitivamente, então você só precisa dele para seus próprios blocos <script> .

Adicionar a integração

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

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

Uma linha em astro.config.mjs. Em cada build a integração escaneia o projeto em busca de @designsetgo/astro/<pack> imports, carrega o manifest de cada componente de node_modules, une as permissões necessárias ao seu dsgo-app.json (preservando todas as outras chaves), e emite um .astro/dsgo-window.d.ts shim para que window.dsgo complete automaticamente com base nas permissões que você realmente declarou.

Importar um componente

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

Cada componente renderiza sua própria marcação, inclui seu próprio CSS com escopo e inicializa automaticamente um pequeno bundle de cliente dentro de um IIFE vinculado ao seu data-dsgo-component slug. Dois componentes na mesma página são slug-isolados; do bundle A mount nunca disparará as raízes do bundle B.

Catálogo de componentes (v0.1.0)

Pacote WooCommerce ( @designsetgo/astro/woo):

Cada componente preserva o comportamento do seu equivalente de bundle independente em examples/woo-*/; um teste de paridade e hook de pre-commit os mantém sincronizados. O catálogo completo com descrições, opções e solução de problemas está no README do pacote.

Modo write vs check

mode: 'write' (padrão) reescreve dsgo-app.json no lugar quando um componente importado adiciona permissões. mode: 'check' encerra o build com código não zero e exibe um diff se o arquivo estiver desatualizado. Use 'check' no CI para que um re-stage esquecido do manifest quebre o build:

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

A mesclagem é apenas aditiva; a integração nunca remove permissões. O modo de desenvolvimento local aplica debounce de 200ms nas mesclagens para que salvar um arquivo que adiciona uma importação não sobrecarregue o manifest.

Montagem com prefixo (padrão)

Sem um bloco mount , o app é servido em /apps/<id>/.... Bom para adicionar uma ferramenta, microsite ou superfície de marketing ao lado de um site WordPress existente, sem alterar o que está em /.

Montagem na raiz (site inteiro)

Para fazer o app Astro ser o próprio site, adicione ao manifest:

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

O app agora é servido em /. As rotas Astro que você declarou controlam os URLs que WordPress atenderia de outra forma; qualquer caminho que WP teria retornado 404 passa pela tabela de rotas. Páginas, posts, arquivos e feeds reais do WordPress ainda têm precedência por padrão; modo raiz adiciona, ela não sobrescreve, então o editor pode continuar publicando em wp-admin.

Se uma rota Astro precisa intencionalmente substituir o WP (por exemplo, um /blog renderizado pelo app, respaldado por wp:posts que colidiria com o arquivo de blog nativo do WordPress), adicionar claim: "always" nessa rota. Consulte reivindicação de rotas.

Build e deploy

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

--build executa npm run build primeiro. O CLI então compacta dist/, valida o manifest, mostra a diferença de capacidade e publica o pacote no endpoint REST do site. Executar novamente deploy atualiza a instalação existente de forma atômica com o mesmo id do app.

No plano Free, apps init --astro e builds locais funcionam; deploy retorna para o upload de bundle no wp-admin (Caminho B). No plano Pro, faça o deploy diretamente pelo terminal.

Cache

• Assets estáticos se invalidam automaticamente. Astro + Vite emitem nomes de arquivo com hash de conteúdo ( app.BYFSNV21.css). Um novo build = um novo hash = invalidação automática de cache edge. É seguro definir max-age por um ano.
• Rotas HTML são públicamente cacheáveis para visitantes anônimos. Os dados por usuário fluem pela ponte em tempo de execução, não pela HTML renderizada no lado do servidor.
• Chamadas do bridge ( /wp-json/dsgo/v1/*) não devem ser armazenadas em cache. O bridge envia Cache-Control: no-store; não sobrescreva com uma regra CDN "Cache Everything".
• URLs de assets em modo root-mount são reescritas para /wp-content/uploads/designsetgo-apps/<id>/... para que o nginx os sirva diretamente, ignorando o PHP.

Orientação completa: cache & CDNs na documentação principal.

Armadilhas comuns

Scripts inline rejeitados no deploy

O sanitizador CSP rejeita bodies <script> inline. Defina vite.build.assetsInlineLimit: 0 em astro.config.mjs para que o Vite emita scripts como arquivos externos. Para origens de terceiros, adicione o host a runtime.csp.script_src.

Página retorna 404 após o deploy

Toda URL deve ser declarada em routes. O file caminho é relativo ao bundle (raiz dist/ ); com format: 'directory', src/pages/about.astro mapeia para about/index.html, não about.html.

Assets 404 em modo root-mount

Em hosts gerenciados (GoDaddy MWP, WP Engine), o nginx pode processar rapidamente .css/.js/.svg requisições antes de o WordPress ser executado. Requer DSGo Apps 0.1.1+, que reescreve as URLs de assets do bundle para o caminho de upload real. Atualize e refaça o deploy. Consulte solução de problemas.

dsgo-app.json ausente do bundle

O manifest deve estar dentro do dist/ quando a CLI compacta. Coloque-o em public/ do Astro, ou copie-o após o build: "build": "astro build && cp dsgo-app.json dist/".

Links quebram ao mudar para montagem na raiz

hrefs codificados diretamente /apps/<id>/ hrefs não funcionarão em /. Sempre crie links via ${import.meta.env.BASE_URL}path para que ambos os modos de montagem funcionem sem alterações no código.

Próximos passos

• Bridge API completa — todos os métodos, códigos de erro e escopos de permissão
• Referência do manifest — o schema dsgo-app.json completo
• Comandos CLI — init, deploy, doctor, flags multi-site
• Permissões — o diálogo de instalação com sete categorias e o que cada permissão concede
• A versão narrativa — mesmo fluxo de trabalho, formato de tutorial

Algo está faltando ou não está claro? Envie-nos um email.