Pular para o conteúdo
v5-beta

Adicione Integrações

Integrações Astro adicionam novas funcionalidades e comportamentos em seu projeto com apenas algumas linhas de código. Você pode usar uma integração oficial, integrações construídas pela comunidade ou até mesmo construir uma integração você mesmo.

Integrações podem…

  • Habilitar React, Vue, Svelte, Solid e outros frameworks de UI populares com um renderer.
  • Habilitar processamento sob demanda com um adaptador SSR.
  • Integrar ferramentas como Tailwind e Partytown com poucas linhas de código.
  • Adicionar novas funcionalidades ao seu projeto, como geração automática de sitemap.
  • Escrever código personalizado que se integra ao processo de build, ao servidor de desenvolvimento e mais.

Integrações Oficiais

Seção intitulada Integrações Oficiais

As seguintes integrações são mantidas pelo Astro.

Frameworks de UI

Adaptadores de SSR

Outras integrações

Instalação Automática de Integração

Seção intitulada Instalação Automática de Integração

Astro inclui o comando astro add para automatizar a instalação de integrações oficiais. Diversos plugins da comunidade podem ser adicionados usando esse comando. Por favor confira a documentação de cada integração para ver se há suporte para astro add, ou se você precisa instalar manualmente.

Execute o comando astro add usando o gerenciador de pacotes de sua escolha e nosso assistente automático de integração atualizará seu arquivo de configuração e instalará quaisquer dependências necessárias.

Janela do terminal
npx astro add react

É possível até mesmo adicionar múltiplas integrações de uma vez só!

Janela do terminal
npx astro add react tailwind partytown

Instalação Manual

Seção intitulada Instalação Manual

Integrações Astro são sempre adicionadas pela propriedade integrations do seu arquivo astro.config.mjs.

Existem três maneiras comuns de importar uma integração no seu projeto Astro:

  1. Instale uma integração com pacote npm.

  2. Importe sua própria integração de um arquivo local dentro do seu projeto.

  3. Escreva sua integração em linha, diretamente no seu arquivo de configuração.

    astro.config.mjs
    import { defineConfig } from 'astro/config';
    import installedIntegration from '@astrojs/vue';
    import localIntegration from './my-integration.js';
    

    export default defineConfig({
      integrations: [
        // 1. Importado de um pacote npm instalado
        installedIntegration(),
        // 2. Importado de um arquivo JS local
        localIntegration(),
        // 3. Um objeto em linha
        {name: 'namespace:id', hooks: { /* ... */ }},
      ]
    });

Confira a referência da API de Integrações para aprender sobre todas as maneiras diferentes que você pode escrever uma integração.

Instalando um pacote NPM

Seção intitulada Instalando um pacote NPM

Instale uma integração de pacote NPM usando um gerenciador de pacotes, e então atualize manualmente o astro.config.mjs.

Por exemplo, para instalar a integração @astrojs/sitemap:

  1. Instale a integração nas dependências do seu projeto usando o seu gerenciador de pacote preferido:

    Janela do terminal
    npm install @astrojs/sitemap

  2. Importe a integração para seu arquivo astro.config.mjs, e adicione-a ao seu array integrations[], junto de quaisquer opções de configuração:

    astro.config.mjs
    import { defineConfig } from 'astro/config';
    import sitemap from '@astrojs/sitemap';
    

    export default defineConfig({
      // ...
      integrations: [sitemap()],
      // ...
    });

    Observe que integrações diferentes podem ter diferentes definições de configuração. Leia a documentação de cada integração, e aplique quaisquer opções de configurações necessárias para a integração escolhida em astro.config.mjs

Opções Personalizadas

Seção intitulada Opções Personalizadas

Integrações são quase sempre escritas como funções factory que retornam o próprio objeto de integração. Isso permite que você passe argumentos e opções para a função factory que personaliza a integração do seu projeto.

integrations: [
  // Exemplo: Personalize sua integração com argumentos de função
  sitemap({filter: true})
]

Alterne uma Integração

Seção intitulada Alterne uma Integração

Integrações com valor falso são ignoradas, então você pode alternar a ativação de integrações sem precisar se preocupar com valores booleanos e undefined esquecidos.

integrations: [
  // Exemplo: Pule construir um sitemap no Windows
  process.platform !== 'win32' && sitemap()
]

Atualizando Integrações

Seção intitulada Atualizando Integrações

Para atualizar todas as integrações oficiais de uma vez só, execute o comando @astrojs/upgrade. Isso atualizará o Astro e todas as integrações oficiais para as últimas versões.

Atualizando Automaticamente

Seção intitulada Atualizando Automaticamente
Janela do terminal
# Atualize Astro e as integrações oficiais para as mais recentes
npx @astrojs/upgrade

Atualizando Manualmente

Seção intitulada Atualizando Manualmente

Para atualizar uma ou mais integrações manualmente, use o comando apropriado em seu gerenciador de pacote.

Janela do terminal
# Exemplo: atualiza integrações React e Tailwind
npm install @astrojs/react@latest @astrojs/tailwind@latest

Removendo uma Integração

Seção intitulada Removendo uma Integração

Para remover uma integração, primeiro desinstale a integração do seu projeto

Janela do terminal
npm uninstall @astrojs/react

Depois, remova a integração do seu arquivo astro.config.*:

astro.config.mjs
import { defineConfig } from 'astro/config'


import react from '@astrojs/react';


export default defineConfig({
  integrations: [
    react()
  ]
})

Encontrando Mais Integrações

Seção intitulada Encontrando Mais Integrações

Você pode encontrar várias integrações desenvolvidas pela comunidade no Diretório de Integrações Astro. Siga os links para instruções detalhadas de uso e configuração.

Criando sua Própria Integração

Seção intitulada Criando sua Própria Integração

A API de Integrações do Astro foi inspirada pelo Rollup e Vite, e projetada para parecer familiar a qualquer um que já tenha escrito um plugin Rollup ou Vite anteriormente.

Veja a referência da API de Integrações para aprender o que integrações podem fazer e como escrever uma você mesmo.

Contribua

O que passa em sua cabeça?

Criar uma Issue no GitHub

A maneira mais rápida de alertar nosso time sobre um problema.

Comunidade