Pular para o conteúdo
Astro Astro

Referência da Configuração

A referência a seguir cobre todas as opções de configuração suportadas no Astro. Para aprender mais sobre como configurar o Astro, leia o nosso guia, Configurando Astro.

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


export default defineConfig({
  // suas opções de configuração aqui...
})

Opções Top-Level

root

Tipo: string
Interface de Linha de Comando: --root
Padrão: "." (diretório de trabalho atual)

Você deve apenas providenciar esta opção se você executar os comandos da interface de linha de comando astro em um diretório diferente do que o diretório raiz do projeto. Geralmente, esta opção é providenciada pela interface de linha de comando ao invés do arquivo de configuração Astro, já que Astro precisa saber a raiz do seu projeto antes de poder localizar seu arquivo de configuração.

Se você providenciar um caminho relativo (ex: --root: './meu-projeto') Astro irá resolvê-lo com base no seu diretório de trabalho atual.

Exemplos

{
  root: './diretorio-do-meu-projeto'
}
Terminal window
$ astro build --root ./diretorio-do-meu-projeto

srcDir

Tipo: string
Padrão: "./src"

Define o diretório em que Astro irá ler o seu site.

O valor pode ser tanto um caminho absoluto do sistema ou um caminho relativo a raiz do projeto.

{
  srcDir: './www'
}

publicDir

Tipo: string
Padrão: "./public"

Define o diretório de seus assets estáticos. Arquivos nesse diretório são servidos em / durante o desenvolvimento e são copiados para o diretório de saída durante o processo de build. Esses arquivos serão sempre servidos ou copiados da forma que são, sem transformações ou etapa de bundle.

O valor pode ser tanto um caminho absoluto do sistema ou um caminho relativo a raiz do projeto.

{
  publicDir: './meu-diretorio-public-customizado'
}

outDir

Tipo: string
Padrão: "./dist"

Define o diretório em que astro build escreve a sua build final.

O valor pode ser tanto um caminho absoluto do sistema ou um caminho relativo a raiz do projeto.

{
  outDir: './meu-diretorio-build-customizado'
}

Veja Também:

  • build.server

cacheDir

Tipo: string
Padrão: "./node_modules/.astro"

Define a pasta para deixar em cache artefatos da build. Arquivos nessa pasta vão ser usados em subsequentes builds para acelerar o tempo de build.

O valor pode ser tanto um caminho absoluto no sistema de arquivos ou um caminho relativo a raiz do projeto.

{
  cacheDir: './minha-pasta-de-cache-personalizada'
}

redirects

Tipo: Record.<string, RedirectConfig>
Padrão: {}

Adicionado em: astro@2.9.0

Especifica um mapeamento de redirecionamentos onde a chave é a rota a corresponder e o valor é o caminho pra onde será redirecionado.

Você pode redirecionar tanto rotas estáticas como dinâmicas, mas somente o mesmo tipo de rota. Por exemplo, você não pode ter um redirecionamento '/artigo': '/blog/[...slug]'.

{
  redirects: {
    '/antigo': '/novo',
    '/blog/[...slug]': '/artigos/[...slug]',
  }
}

Para sites estaticamente gerados sem nenhum adaptador instalado, isso vai produzir um redirecionamento no cliente usando uma tag <meta http-equiv="refresh"> e não suporta códigos de status.

Quando estiver usando SSR ou um adaptador estático no modo output: static, códigos de status não são suportados. O Astro irá servir requisições GET redirecionadas com um status de 301 e usar um status de 308 para qualquer outro método de requisição.

Você pode customizar o código de status de redirecionamento usando um objeto na configuração de redirecionamento:

{
  redirects: {
    '/outro': {
      status: 302,
      destination: '/lugar',
    },
  }
}

site

Tipo: string

Sua URL final no deploy. Astro utiliza esta URL completa para gerar seu sitemap e URLs canônicas na sua build final. É fortemente recomendado que você defina esta configuração para usufruir ao máximo o que o Astro pode oferecer.

{
  site: 'https://www.meu-site.dev'
}

compressHTML

Tipo: boolean
Padrão: true

Esta é uma opção para minificar seu HTML final e reduzir o tamanho dos seus arquivos HTML. Por padrão, o Astro remove todos os espaços em branco do seu HTML, incluindo quebras de linha, de componentes .astro. Isso ocorre tanto em modo de desenvolvimento e na build final. Para desabilitar a compressão de HTML, defina a flag compressHTML como false.

{
  compressHTML: false
}

base

Tipo: string

O caminho base no qual será feito o deploy. Astro irá utilizar esse caminho como a raiz para suas páginas e assets tanto em desenvolvimento quanto na build para produção.

No exemplo abaixo, astro dev irá iniciar seu servidor em /docs.

{
  base: '/docs'
}

Au utilizar esta opção, todas as importações de assets e URLs devem adicionar a base como prefixo. Você pode acessar esse valor com import.meta.env.BASE_URL.

O valor de import.meta.env.BASE_URL respeita sua configuração de trailingSlash e irá incluir uma barra final se você explicitamente incluiu uma ou se trailingSlash: "always" foi definido. Se trailingSlash: "never" está definido, BASE_URL não irá incluir uma barra final, mesmo se base inclui uma.

trailingSlash

Tipo: 'always' | 'never' | 'ignore'
Padrão: 'ignore'

Define o comportamento de correspondência de rotas do servidor de desenvolvimento. Escolha entre as seguintes opções:

  • 'always' - Apenas corresponde URLs que incluem uma barra final (ex: “/foo/“)
  • 'never' - Nunca corresponde URLs que incluem uma barra final (ex: “/foo”)
  • 'ignore' - Corresponde URLs independente da presença de uma ”/” final

Use esta opção de configuração se o seu host de produção lida de forma estrita em como barras finais funcionam ou não.

Você também pode definir isto se você preferir ser mais estrito consigo mesmo, para que então URLs com ou sem barras finais não funcionem durante o desenvolvimento.

{
  // Exemplo: Requer uma barra final durante o desenvolvimento
  trailingSlash: 'always'
}

Veja Também:

  • build.format

scopedStyleStrategy

Tipo: 'where' | 'class' | 'attribute'
Padrão: 'attribute'

Adicionado em: astro@2.4

Especifica a estratégia usada para definir o escopo de estilos dentro de componentes do Astro. Escolha entre:

  • 'where' - Usa seletores :where, causando nenhum aumento de especificidade.
  • 'class' - Usa seletores baseados em classe, causando um aumento de +1 de especificidade.
  • 'attribute' - Usa atributos data-, causando nenhum aumento de especificidade.

Usar 'class' é útil quando você quer garantir que os seletores de elementos em componentes Astro sobrescrevam os padrões de estilo globais (e.x. de uma folha de estilo global). Usar 'where' dá a você mais controle sobre a especificidade, mas requer que você use seletores de especificidade mais alta, camadas e outras ferramentas para controlar quais seletores são aplicados. Usar 'attribute' é útil quando você está manipulando o atributo class de elementos e precisa evitar conflitos entre sua própria lógica de estilização e a aplicação de estilos do Astro.

adapter

Tipo: AstroIntegration

Faça deploy para seu servidor de hospedagem, serverless ou edge favorito com adaptadores de build. Importe um dos nossos adaptadores oficiais para Netlify, Vercel e mais para começar a usar SSR no Astro.

Veja nosso guia sobre Renderização no lado do Servidor para mais sobre SSR e nossos guias de deploy para uma lista completa de hospedagem.

import netlify from '@astrojs/netlify/functions';
{
  // Exemplo: Faça build para o serverless da Netlify
   adapter: netlify(),
}

Veja Também:

  • output

output

Tipo: 'static' | 'server' | 'hybrid
Padrão: 'static'

Especifica o alvo de saída para builds.

  • ‘static’ - Fazendo build de um site estático para fazer deploy em qualquer hospedagem estática.
  • ‘server’ - Fazendo build de um app para fazer deploy em uma hospedagem que suporta SSR (renderização no lado do servidor).
  • ‘hybrid’ - Fazendo build de um site estático com algumas páginas renderizadas no lado do servidor.
import { defineConfig } from 'astro/config';


export default defineConfig({
  output: 'static'
})

Veja Também:

  • adapter

Opções da Build

build.format

Tipo: ('file' | 'directory')
Padrão: 'directory'

Controla o formato final do arquivo de cada página.

  • Se for ‘file’, Astro irá gerar um arquivo HTML (ex: “/foo.html”) para cada página.
  • Se for ‘directory’, Astro irá gerar um diretório com um arquivo index.html aninhado (ex: “/foo/index.html”) para cada página.
{
  build: {
    // Exemplo: Gera `pagina.html` ao invés de `pagina/index.html` durante a build.
    format: 'file'
  }
}

Efeito no Astro.url

Definir build.format controla o que Astro.url é durante a build. Quando ele for:

  • directory - O Astro.url.pathname irá incluir uma barra final para imitar o comportamento da pasta; ou seja, /foo/.
  • file - O Astro.url.pathname irá incluir .html; ou seja, /foo.html.

Isso significa que quando você criar URLs relativas usando new URL('./relativo', Astro.url), você terá um comportamento consistente entre dev e build.

Para evitar inconsistências com o comportamento da barra final durante desenvolvimento, você pode restringir a opção trailingSlash para 'always' ou 'never' dependendo do seu formato de build:

  • directory - Defina trailingSlash: 'always'
  • file - Defina trailingSlash: 'never'

build.client

Tipo: string
Padrão: './dist/client'

Controla o diretório de saída do seu CSS e JavaScript do lado do cliente apenas quando output: 'server' ou output: 'hybrid'. outDir controla onde o código é construído.

Esse valor é relativo ao outDir.

{
  output: 'server', // ou 'hybrid'
  build: {
    client: './client'
  }
}

build.server

Tipo: string
Padrão: './dist/server'

Controla o diretório de saída de JavaScript do servidor ao fazer build para SSR.

Esse valor é relativo ao outDir.

{
  build: {
    server: './server'
  }
}

build.assets

Tipo: string
Padrão: '_astro'

Adicionado em: astro@2.0.0

Especifica o diretório na saída da build onde assets gerados pelo Astro (JS e CSS pós-bundle por exemplo) deve ficar.

{
  build: {
    assets: '_customizado'
  }
}

Veja Também:

  • outDir

build.assetsPrefix

Tipo: string
Padrão: undefined

Adicionado em: astro@2.2.0

Especifica o prefixo para links de assets gerados pelo Astro. Isto pode ser utilizado se assets são servidos de um domínio diferente do site atual.

Por exemplo, se ele é definido como https://cdn.exemplo.com, assets serão buscados de https://cdn.exemplo.com/_astro/... (independente da opção base). Você precisaria fazer upload desses arquivos em ./dist/_astro/ para https://cdn.exemplo.com/_astro/ para providenciar os assets. O processo varia dependendo em como o domínio de terceiros é hospedado. Para renomear o caminho _astro, especifique um novo diretório em build.assets.

{
  build: {
    assetsPrefix: 'https://cdn.exemplo.com'
  }
}

build.serverEntry

Tipo: string
Padrão: 'entry.mjs'

Especifica o nome de arquivo do entrypoint do servidor ao fazer build para SSR. Esse entrypoint geralmente depende em qual provedor você está fazendo o deploy e será definido pelo seu adaptador por você.

Note que é recomendado que este arquivo termine com .mjs para que o runtime detecta que o arquivo é um módulo JavaScript.

{
  build: {
    serverEntry: 'main.mjs'
  }
}

build.redirects

Tipo: boolean
Padrão: true

Adicionado em: astro@2.6.0

Especifica se os redirecionamentos são enviados como HTML durante a build. Essa opção só se aplica para o modo output: 'static'; em SSR os redirecionamentos são tratados da mesma forma que todas as respostas.

Essa opção é principalmente para ser usada por adaptadores que possuem arquivos de configuração especiais para redirecionamentos e não precisam/querem redirecionamentos baseados em HTML.

{
  build: {
    redirects: false
  }
}

build.inlineStylesheets

Tipo: 'always' | 'auto' | 'never'
Padrão: auto

Adicionado em: astro@2.6.0

Controla se os estilos do projeto são enviados para o navegador em um arquivo CSS separado ou em linha em tags <style>. Escolha entre as seguintes opções:

  • 'always' - estilos do projeto são embutidos em tags <style>
  • 'auto' - apenas folhas de estilo menores que ViteConfig.build.assetsInlineLimit (padrão: 4kb) são embutidas. Caso contrário, estilos do projeto são enviados em folhas de estilo externas.
  • 'never' - estilos do projeto são enviados em folhas de estilo externas
{
  build: {
    inlineStylesheets: `never`,
  },
}

build.split

Tipo: boolean
Padrão: false

A opção de configuração da build build.split foi substituída pela opção de configuração do adaptador functionPerRoute.

Por favor veja a documentação do seu adaptador SSR para utilizar functionPerRoute para definir como seu código SSR deve passar por bundle.

{
  build: {
    split: true
  }
}

build.excludeMiddleware

Tipo: boolean
Padrão: false

A opção de configuração da build build.excludeMiddleware foi substituída pela opção de configuração do adaptador edgeMiddleware.

Por favor veja a documentação do seu adaptador SSR para utilizar edgeMiddleware para definir se algum ou nenhum código de middleware SSR irá passar por bundle durante a build.

{
  build: {
    excludeMiddleware: true
  }
}

Opções do Servidor

Customize o servidor de desenvolvimento do Astro, usado por astro dev e astro preview.

{
  server: { port: 1234, host: true }
}

Para definir uma configuração diferente baseada no comando run (“dev”, “preview”) uma função também pode ser passada para esta opção de configuração.

{
  // Exemplo: Use a sintaxe de função para customizar com base no comando
  server: ({ command }) => ({ port: command === 'dev' ? 4321 : 4000 })
}

server.host

Tipo: string | boolean
Padrão: false

Adicionado em: astro@0.24.0

Define em quais endereços de IP da rede o servidor deve ser escutado em (ou seja, IPs que não sejam localhost).

  • false - não o expõe em um endereço de IP da rede
  • true - escutado em todos os endereços, incluindo endereços LAN e públicos
  • [endereço-customizado] - o expõe ao endereço de IP da rede em [endereço-customizado] (ex: 192.168.0.1)

server.port

Tipo: number
Padrão: 4321

Define em qual porta o servidor deve ser escutado.

Se a porta indicada já estiver em uso, Astro irá automaticamente tentar a próxima porta disponível.

{
  server: { port: 8080 }
}

server.headers

Tipo: OutgoingHttpHeaders
Padrão: {}

Adicionado em: astro@1.7.0

Define headers de resposta HTTP customizados a serem enviados em astro dev e astro preview.

Opções de Imagem

image.service (Experimental)

Tipo: Object
Padrão: {entrypoint: 'astro/assets/services/sharp', config?: {}}

Adicionado em: astro@2.1.0

Defina que serviço de imagem será usado para o suporte experimental de assets do Astro.

O valor deve ser um objeto com um entrypoint para o serviço de imagem a ser usado e opcionalmente, um objeto de configuração para passar ao serviço.

O entrypoint do serviço pode ser tanto um dos serviços inclusos ou um pacote de terceiros.

{
  image: {
    // Exemplo: Habilite o serviço de imagem baseado no Sharp
    service: { entrypoint: 'astro/assets/services/sharp' },
  },
}

image.domains

Tipo: Array.<string>
Padrão: {domains: []}

Adicionado em: astro@2.10.10

Define uma lista de domínios de fonte de imagem permitidos para otimização de imagem local. Nenhuma outra imagem remota vai ser otimizada pelo Astro.

Essa opção requer uma matriz de nomes de domínio individuais como strings. Coringas não são permitidos. Ao invés disso, use image.remotePatterns para definir uma lista de padrões de URL de origens permitidos.

astro.config.mjs
{
  image: {
    // Exemplo: Permitir otimização de imagem remota de um único domínio
    domains: ['astro.build'],
  },
}

image.remotePatterns

Tipo: Array.<RemotePattern>
Padrão: {remotePatterns: []}

Adicionado em: astro@2.10.10

Define uma lista de padrões de URL de origem de imagem permitidos para otimização de imagem local.

remotePatterns pode ser configurado com quatro propriedades:

  1. protocol
  2. hostname
  3. port
  4. pathname
{
  image: {
    // Exemplo: permitir processamento de todas as imagens do seu bucket do aws s3
    remotePatterns: [{
      protocol: 'https',
      hostname: '**.amazonaws.com',
    }],
  },
}

Você pode usar coringas para definir os valores permitidos de hostname e pathname como descrito abaixo. Caso contrário, apenas os valores exatos fornecidos serão configurados: hostname:

  • Comece com ’**.’ para permitir todos os subdomínios (‘termina com’).
  • Comece com ’*.’ para permitir apenas um nível de subdomínio.

pathname:

  • Termine com ’/**’ para permitir todas as sub-rotas (‘começa com’).
  • Termine com ’/*’ para permitir apenas um nível de sub-rota.

Opções de Markdown

markdown.drafts

Tipo: boolean
Padrão: false

Controla se páginas de rascunho Markdown devem ser inclusas na build.

Uma página Markdown é considerada um rascunho se ela inclui draft: true em seu frontmatter. Páginas de rascunho estarão sempre inclusas e visíveis durante o desenvolvimento (astro dev) mas por padrão elas não serão inclusas em sua build final.

{
  markdown: {
    // Exemplo: Inclui todos os rascunhos em sua build final
    drafts: true,
  }
}

markdown.shikiConfig

Tipo: Partial<ShikiConfig>

Opções da configuração do Shiki. Veja a documentação da configuração de Markdown para entender como configurá-lo.

markdown.syntaxHighlight

Tipo: 'shiki' | 'prism' | false
Padrão: shiki

Qual syntax highlighter deve ser utilizado, caso utilize.

  • shiki - utiliza o highlighter do Shiki
  • prism - utiliza o highlighter do Prism
  • false - não aplica syntax highlighting.
{
  markdown: {
    // Exemplo: Mudando para utilizar prism como syntax highlighter em Markdown
    syntaxHighlight: 'prism',
  }
}

markdown.remarkPlugins

Tipo: RemarkPlugins

Passe plugins remark para customizar como seu Markdown é construído. Você pode importar e aplicar a função do plugin (recomendado), ou passar o nome do plugin como uma string.

import remarkToc from 'remark-toc';
{
  markdown: {
    remarkPlugins: [remarkToc]
  }
}

markdown.rehypePlugins

Tipo: RehypePlugins

Passe plugins rehype para customizar como o HTML resultante do seu Markdown é processado. Você pode importar e aplicar a função do plugin (recomendado), ou passar o nome do plugin como uma string.

import rehypeMinifyHtml from 'rehype-minify';
{
  markdown: {
    rehypePlugins: [rehypeMinifyHtml]
  }
}

markdown.gfm

Tipo: boolean
Padrão: true

Adicionado em: astro@2.0.0

Astro usa GitHub-flavored Markdown por padrão. Para desabilitá-lo, defina a flag gfm como false:

{
  markdown: {
    gfm: false,
  }
}

markdown.smartypants

Tipo: boolean
Padrão: true

Adicionado em: astro@2.0.0

Astro usa o formatador SmartyPants por padrão. Para desabilitá-lo, defina a flag smartypants como false:

{
  markdown: {
    smartypants: false,
  }
}

markdown.remarkRehype

Tipo: RemarkRehype

Passe opções para o remark-rehype.

{
  markdown: {
    // Exemplo: Traduza o texto das notas de rodapé para outra língua, aqui estão os valores padrões em Inglês
    remarkRehype: { footnoteLabel: "Footnotes", footnoteBackLabel: "Back to content"},
  },
};

Integrações

Estenda Astro com integrações customizadas. Integrações são sua via de mão única para adicionar suporte a frameworks (como Solid.js), novas funcionalidades (como sitemaps) e novas bibliotecas (como Partytown).

Leia nosso Guia de Integrações para mais ajuda em como começar a utilizar Integrações Astro.

import react from '@astrojs/react';
import tailwind from '@astrojs/tailwind';
{
  // Exemplo: Adicione suporte a React + Tailwind no Astro
  integrations: [react(), tailwind()]
}

Vite

Passe opções de configuração adicionais ao Vite. Útil quando o Astro não suporta algumas configurações avançadas que você pode precisar.

Veja a documentação completa do objeto de configuração vite em vitejs.dev.

Exemplos

{
  vite: {
    ssr: {
      // Exemplo: Force um pacote quebrado a pular o processamento SSR, se necessário
      external: ['pacote-npm-quebrado'],
    }
  }
}
{
  vite: {
    // Exemplo: Adicione plugins vite customizados diretamente em seu projeto Astro
    plugins: [meuPlugin()],
  }
}

Flags Legado

Para ajudar usuários a migrarem entre versões do Astro, nós ocasionalmente introduzimos flags legacy. Estas flags te permitem optar por um descontinuado ou antigo comportamento do Astro na versão mais recente, para que então você possa continuar atualizando e se aproveitando de novas versões do Astro.

Flags Experimentais

Astro oferece flags experimentais para dar aos usuários acesso antecipado a novas funcionalidades. Não há garantia que essas flags são estáveis.

experimental.optimizeHoistedScript

Tipo: boolean
Padrão: false

Adicionado em: astro@2.10.4

Previne que scripts de componentes não utilizados sejam incluídos em uma página de forma inesperada. A otimização é feita com base na melhor estimativa e pode inversamente deixar de incluir scripts utilizados. Tenha certeza de que checou as páginas da sua build antes de publicar. Habilite a otimização por análise de scripts hoisted adicionando a flag experimental:

{
  experimental: {
    optimizeHoistedScript: true,
  },
}