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, AlpineJS e Lit. Uma ou várias destas integrações Astro podem ser instaladas e configuradas em seu projeto.

⚙️ 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.jsx';
---
<html>
  <body>
    <h1>Use componentes React diretamente no Astro!</h1>
    <MeuComponenteReact />
  </body>
</html>

Por padrão, seus componentes de frameworks serão renderizados apenas no servidor, 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 se tornar interativo (hidratado) utilizando uma diretiva client:*. Elas são atributos de componente que determinam quando o JavaScript do seu componente deve ser enviado ao navegador.

Com todas as diretivas de cliente exceto client:only, seu componente será primeiro renderizado no servidor para gerar HTML estático. JavaScript do componente será enviado ao navegador de acordo com a diretiva que você escolheu. O componente será então hidratado e se tornará interativo.

---
// Exemplo: hidratando componentes de frameworks no navegador.
import BotaoInterativo from '../components/BotaoInterativo.jsx';
import ContadorInterativo from '../components/ContadorInterativo.jsx';
import ModalInterativo from "../components/InteractiveModal.svelte"
---
<!-- 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 />

<!-- Este componente não será renderizado no servidor, mas será renderizado no cliente quando a página carregar -->
<ModalInterativo client:only="svelte" />

O framework JavaScript (React, Svelte, etc) necessário para renderizar o componente será enviado ao navegador junto do JavaScript do próprio componente. Se dois ou mais componentes em uma página usam o mesmo framework, o framework será enviado apenas uma vez.

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.jsx';
import MeuComponenteSvelte from '../components/MeuComponenteSvelte.svelte';
import MeuComponenteVue from '../components/MeuComponenteVue.vue';
---
<div>
  <MeuComponenteSvelte />
  <MeuComponenteReact />
  <MeuComponenteVue />
</div>

Passando Props Para Componentes de Frameworks

Você pode passar props de componentes Astro para componentes de frameworks:

---
import ListaDeFazeres from '../components/ListaDeFazeres.jsx';
import Contador from '../components/Contador.svelte';
---
<div>
  <ListaDeFazeres fazeresIniciais={["aprender Astro", "revisar PRs"]} />
  <Contador contagemInicial={1} />
</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 atributo 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.jsx';
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 utilizar Componentes Astro dentro de meus Componentes de Frameworks?

Qualquer componente de framework de UI se torna uma “ilha” daquele framework. Esses componentes precisam ser escritos inteiramente como código válido para aquele framework, usando apenas suas importações e pacotes. Você não pode importar componentes .astro em um componente de framework de UI (e.x. .jsx ou .svelte).

Você pode, no entanto, utilizar o padrão de <slot /> do Astro para passar conteúdo gerado estaticamente por componentes Astro como filhos de seus componentes de frameworks dentro de um componente .astro.

---
import MeuComponenteReact from '../components/MeuComponenteReact.jsx';
import MeuComponenteAstro from '../components/MeuComponenteAstro.astro';
---
<MeuComponenteReact>
  <MeuComponenteAstro slot="nome" />
</MeuComponenteReact>

Posso utilizar Componentes Astro dentro de meus Componentes de Framework?

Qualquer componente de framework UI se torna uma “ilha” daquele framework. Esses componentes devem ser escritos inteiramente como código válido para o framework, usando apenas suas próprias importações e pacotes. Você não pode importar componentes .astro em um componente de framework UI (e.x. .jsx ou .svelte).

Você pode, porém, utilizar o padrão <slot /> do Astro para passar conteúdo estático gerado por componentes Astro como filhos de seus componentes de framework dentro de um componente .astro.

---
import MeuComponenteReact from '../components/MeuComponenteReact.jsx';
import MeuComponenteAstro from '../components/MeuComponenteAstro.astro';
---
<MeuComponenteReact>
  <MeuComponenteAstro slot="nome" />
</MeuComponenteReact>

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.

Contribua

Comunidade