Configuração de ilhas Astro e React

Para iniciar um projeto Astro, use npx create astro@latest, que executa um assistente interativo para escolher um modelo, as configurações de TypeScript e o gerenciador de pacotes. O Astro oferece vários projetos iniciais, incluindo um modelo em branco, um modelo de blog e modelos de documentação.

As integrações do Astro adicionam suporte a estruturas de desenvolvimento a um projeto. A execução de npx astro add react instala automaticamente @astrojs/react, react e react-dom, além de atualizar astro.config.mjs para incluir a integração com React. Toda a configuração é feita com um único comando.

Um arquivo .astro é o formato de componente do Astro. Ele consiste em uma seção de cabeçalho inicial (JavaScript entre delimitadores ---) e uma seção de modelo. Por padrão, um arquivo Astro gera HTML estático — nenhum JavaScript é enviado ao navegador, a menos que você adicione explicitamente uma diretiva de cliente.

Para importar um componente React em um arquivo Astro, use a sintaxe padrão de módulo ES: import Counter from './Counter.jsx'. Sem uma diretiva de cliente, o Astro renderiza o componente React no servidor como HTML estático e envia esse HTML ao navegador — nenhum JavaScript é enviado para o componente.

Adicionar client:visible à tag do componente no modelo Astro transforma-o em uma ilha: <Counter client:visible />. Agora o Astro envia o JavaScript de Counter, hidrata-o quando ele entra na área visível e o torna interativo. Sem a diretiva, ele é apenas HTML estático.

Os componentes React usados como ilhas do Astro são escritos em React padrão — eles usam ganchos, estado, efeitos e qualquer biblioteca do React. Não existe uma API específica do Astro dentro do próprio componente React. O limite da ilha é definido no modelo Astro, não no código do componente.

Cada instância de uma ilha é uma árvore React independente. Duas ilhas Counter na mesma página não compartilham estado. Se você precisar compartilhar estado, terá três opções: uni-las em uma única ilha, usar parâmetros de consulta da URL para armazenar estado serializável ou usar uma biblioteca de estado compartilhado, como nanostores.

A biblioteca @nanostores/react fornece átomos leves aos quais qualquer ilha pode se inscrever. Uma ilha grava dados em um átomo de nanostores, e outra ilha os lê. Como nanostores são independentes de estrutura de desenvolvimento, esse padrão também funciona entre ilhas de React e Vue na mesma página.

As Coleções de Conteúdo do Astro oferecem uma maneira segura quanto aos tipos de gerenciar arquivos Markdown e MDX. Defina um esquema de coleção com Zod, coloque os arquivos Markdown em src/content/ e o Astro gerará funções de consulta totalmente tipadas. Esse é o padrão para publicações de blog, documentação e páginas de produtos.

A execução de astro build gera uma pasta dist/ com arquivos HTML estáticos. Para cada página, o Astro gera um arquivo HTML com o conteúdo renderizado no servidor e somente os pacotes de JavaScript necessários para as ilhas daquela página. Páginas sem ilhas não geram nenhum JavaScript.

A saída estática pode ser implantada em qualquer CDN (Netlify, Vercel, Cloudflare Pages), sem um servidor. Para necessidades de renderização no servidor (rotas dinâmicas e pontos de acesso de API), o Astro oferece adaptadores de SSR para Node.js, Vercel Edge, Cloudflare Workers e Deno. As ilhas funcionam da mesma maneira nos dois modos.

Qual é a alteração mínima necessária em um componente React importado em um modelo Astro para torná-lo interativo no cliente?

Configure o Astro com React usando npx astro add react. Os arquivos Astro são estáticos por padrão; adicionar uma diretiva client: à tag de um componente React transforma-o em uma ilha hidratada. Os componentes React seguem o React padrão, sem APIs específicas do Astro. O estado é isolado por ilha; nanostores permitem a comunicação entre ilhas. A compilação gera HTML estático com apenas o JavaScript necessário para as ilhas.