Componentes de Frameworks

Construa seu website Astro sem sacrificar o seu framework de componentes favorito.

Astro suporta uma variedade de frameworks populares incluindo React, Preact, Svelte, Vue, SolidJS, AlpineJS e Lit.

Instalando Integrações

Astro vem com integrações opcionais para React, Preact, Svelte, Vue, SolidJS e Lit. Uma ou mais destas integrações podem ser instaladas e configuradas no seu projeto.

Para configurar Astro para utilizar estes frameworks, primeiro, instale sua integração e quaisquer dependências associadas:

npm install --save-dev @astrojs/react react react-dom

Então importe e adicione a função a sua lista de integrações em astro.config.mjs:

import { defineConfig } from 'astro/config';

import react from '@astrojs/react';
import preact from '@astrojs/preact';
import svelte from '@astrojs/svelte';
import vue from '@astrojs/vue';
import solid from '@astrojs/solid-js';
import lit from '@astrojs/lit';

export default defineConfig({
  integrations: [react(), preact(),svelte(), vue(), solid() , lit()],
});

⚙️ Veja o Guia de Integrações para mais detalhes em como instalar e configurar integrações Astro.

⚙️ Quer ver um exemplo do framework de sua escolha? Visite astro.new e selecione um dos templates de frameworks.

Usando Componentes de Frameworks

Utilize os componentes de frameworks JavaScript em suas páginas, layouts e componentes Astro assim como você utilizaria componentes Astro! Todos os seus componentes podem estar juntos em /src/components, ou podem ser organizados da forma que você preferir.

Para usar um componente de framework, importe-o de seu caminho relativo no script do componente Astro. Então, use o componente ao lado de outros componentes, como elementos HTML e expressões estilo JSX no template do componente.

---
import MeuComponenteReact from '../components/MeuComponenteReact';
import MeuComponenteSvelte from '../components/MeuComponenteSvelte.svelte';
---
<html>
  <body>
    <h1>Use componentes React e Svelte diretamente no Astro!</h1>
    <MeuComponenteReact />
    <MeuComponenteSvelte />
  </body>
</html>

Por padrão, seus componentes de frameworks serão renderizados como HTML estático. Isso é útil para fazer o template de componentes que não são interativos e evita mandar qualquer JavaScript desnecessário ao cliente.

Hidratando Componentes Interativos

Um componente de framework pode ser tornar interativo (hidratado) utilizando uma das diretivas client:*. Isso é um atributo de componente que define como seu componente deve ser renderizado e hidratado.

Uma diretiva de cliente descreve se o seu componente deve ou não ser renderizado no momento de build e quando o JavaScript do seu componente deve ser carregado pelo navegador, no lado do cliente.

A maioria das diretivas irá renderizar o componente no servidor no momento de build. O JavaScript do componente será enviado ao cliente de acordo com a diretiva especificada. O componente será hidratado quando o seu JS terminar de ser importado.

---
// Exemplo: hidratando componentes de frameworks no navegador.
import BotaoInterativo from '../components/BotaoInterativo';
import ContadorInterativo from '../components/ContadorInterativo';
---
<!-- O JS desse componente começará a ser importado quando a página carregar -->
<BotaoInterativo client:load />

<!-- O JS desse componente não será enviado ao cliente até que o usuário role a tela até o componente estar visível na página -->
<ContadorInterativo client:visible />

Diretivas de Hidratação Disponível

Há diversas diretivas de hidratação disponíveis para componentes de frameworks de UI: client:load, client:idle, client:visible, client:media={QUERY} e client:only={FRAMEWORK}.

📚 Veja nossa página de referência de diretivas para uma descrição completa destas diretivas de hidratação e seus usos.

Misturando Frameworks

Você pode importar e renderizar componentes de múltiplos frameworks em um mesmo componente Astro.

---
// Exemplo: Misturando múltiplos componentes de frameworks na mesma página.
import MeuComponenteReact from '../components/MeuComponenteReact';
import MeuComponenteSvelte from '../components/MeuComponenteSvelte.svelte';
import MeuComponenteVue from '../components/MeuComponenteVue.vue';
---
<div>
  <MeuComponenteSvelte />
  <MeuComponenteReact />
  <MeuComponenteVue />
</div>

Passando Filhos para Componentes de Frameworks

Dentro de um componente Astro, você pode passar filhos para componentes de frameworks. Cada framework tem seus próprios padrões para como se referenciar a esses filhos: React, Preact, e Solid usam todos uma prop especial chamada children, enquanto Svelte e Vue usam o elemento <slot />.

---
import MinhaBarraLateralReact from '../components/MinhaBarraLateralReact.jsx';
---
<MinhaBarraLateralReact>
  <p>Aqui está uma barra lateral com algum texto e um botão.</p>
</MinhaBarraLateralReact>

Adicionalmente, você pode usar Slots Nomeados para agrupar filhos específicos juntos.

Para React, Preact, e Solid esses slots serão convertidos em uma prop top-level. Nomes de slots usandokebab-case serão convertidos para camelCase.

---
import MinhaBarraLateral from '../components/MinhaBarraLateral.jsx';
---
<MinhaBarraLateral>
  <h2 slot="titulo">Menu</h2>
  <p>Aqui está uma barra lateral com algum texto e um botão.</p>
  <ul slot="social-links">
    <li><a href="https://twitter.com/astrodotbuild">Twitter</a></li>
    <li><a href="https://github.com/withastro">GitHub</a></li>
  </ul>
</MinhaBarraLateral>

export default function MinhaBarraLateral(props) {
  return (
    <aside>
      <header>{props.titulo}</header>
      <main>{props.children}</main>
      <footer>{props.socialLinks}</footer>
    </aside>
  )
}

Para Svelte e Vue esses slots podem ser referenciados utilizando um elemento <slot> com o attributo name. Nomes de slots usando kebab-case serão preservados.

<aside>
  <header><slot name="titulo" /></header>
  <main><slot /></main>
  <footer><slot name="social-links" /></footer>
</aside>

Aninhando Componentes de Frameworks

Dentro de um arquivo Astro, filhos de componentes de frameworks também podem ser componentes hidratados. Isso significa que você pode recursivamente aninhar componentes de qualquer um desses frameworks.

---
import MinhaBarraLateralReact from '../components/MinhaBarraLateralReact';
import MeuBotaoReact from '../components/MeuBotaoReact.jsx';
import MeuBotaoSvelte from '../components/MeuBotaoSvelte.svelte';
---
<MinhaBarraLateralReact>
  <p>Aqui está uma barra lateral com algum texto e um botão.</p>
  <div slot="acoes">
    <MeuBotaoReact client:idle />
    <MeuBotaoSvelte client:idle />
  </div>
</MinhaBarraLateralReact>

Isso te permite construir “aplicativos” inteiros com seu framework JavaScript favorito e o renderizar, via um componente parente, em uma página Astro.

Posso Hidratar Componentes Astro?

Se você tentar hidratar um componente Astro com um modificador client:, você receberá um erro.

Componentes Astro são componentes de template de apenas HTML que não possuem runtime no lado do cliente. Porém, você pode usar uma tag <script> no template do seu componente Astro para enviar JavaScript ao navegador que é executado no escopo global.

📚 Aprenda mais sobre <scripts> no lado do cliente em componentes Astro.