Pular para o conteúdo

Configurando Astro

Customize o funcionamento do Astro adicionando um arquivo astro.config.mjs em seu projeto. Este é um arquivo comum em projetos Astro e todos os templates oficiais o incluem por padrão.

📚 Leia a referência de configuração da API do Astro para uma visão geral de todas as opções de configuração suportadas.

Um arquivo de configuração Astro válido exporta sua configuração com a exportação default, usando a função auxiliar defineConfig:

astro.config.mjs
import { defineConfig } from 'astro/config'
export default defineConfig({
// suas opções de configuração aqui...
// https://docs.astro.build/pt-br/reference/configuration-reference/
})

Usar defineConfig() é recomendado para dicas de tipagem automáticas na sua IDE porém também é opcional. Uma configuração mínima válida se pareceria com algo assim:

astro.config.mjs
// Exemplo: Configuração mínima, um arquivo vazio
export default {}

Tipos de Arquivo de Configuração Suportados

Seção intitulada Tipos de Arquivo de Configuração Suportados

Astro suporta outros formatos de arquivos para seu arquivo de configuração JavaScript: astro.config.js, astro.config.mjs, astro.config.cjs e astro.config.ts. Nós recomendamos utilizar .mjs na maioria dos casos ou .ts se você quiser escrever TypeScript no seu arquivo de configuração.

O arquivo de configuração TypeScript é gerenciado usando o tsm e irá respeitar as opções definidas no tsconfig do seu projeto.

Resolução do Arquivo de Configuração

Seção intitulada Resolução do Arquivo de Configuração

Astro irá tentar buscar automaticamente um arquivo de configuração com o nome astro.config.mjs na raiz de seu projeto. Se nenhum arquivo for encontrado, as opções padrão do Astro serão utilizadas.

Terminal window
# Exemplo: Lê sua configuração em ./astro.config.mjs
astro build

Você pode passar o arquivo de configuração explicitamente usando a opção --config da interface de linha de comando. Esta opção sempre busca o arquivo relativo ao diretório no qual você está executando o comando astro em seu terminal.

Terminal window
# Exemplo: Lê suas opções de configuração neste arquivo
astro build --config minha-configuracao.js

Astro recomenda o uso da função auxiliar defineConfig() em seu arquivo de configuração. defineConfig() proporciona IntelliSense automático em sua IDE. Editores como VSCode são capazes de ler as definições de tipo TypeScript do Astro e providencia dicas de tipagem JSDoc automáticas, mesmo que seu arquivo de configuração não esteja escrito em TypeScript.

astro.config.mjs
import { defineConfig } from 'astro/config'
export default defineConfig({
// Seu arquivo de configuração aqui...
// https://docs.astro.build/pt-br/reference/configuration-reference/
})

Você também pode providenciar manualmente as definições de tipo para o VSCode, usando essa notação JSDoc:

astro.config.mjs
export default /** @type {import('astro').AstroUserConfig} */ {
// Seu arquivo de configuração aqui...
// https://docs.astro.build/pt-br/reference/configuration-reference/
}

Se você providenciar um caminho relativo à opção root ou passar a opção --root da interface de linha de comando, Astro irá resolver os arquivos de acordo com o diretório que o comando astro estiver executando.

astro.config.mjs
import { defineConfig } from 'astro/config'
export default defineConfig({
// Resolve o caminho "./foo" em seu diretório de trabalho atual.
root: 'foo'
})

Astro irá resolver todos os outros arquivos e diretórios relativos à raiz do projeto definida:

astro.config.mjs
import { defineConfig } from 'astro/config'
export default defineConfig({
// Resolve o caminho "./foo" em seu diretório de trabalho atual.
root: 'foo',
// Resolve o caminho "./foo/public" em seu diretório de trabalho atual.
publicDir: 'public',
})

Para referenciar um arquivo ou diretório relativo ao arquivo de configuração, use import.meta.url (a menos que você esteja em um arquivo common.js astro.config.cjs):

astro.config.mjs
import { defineConfig } from 'astro/config'
export default defineConfig({
// Resolve o caminho "./foo" relativo a este arquivo de configuração.
root: new URL("./foo", import.meta.url).toString(),
// Resolve o caminho "./public" relativo a este arquivo de configuração.
publicDir: new URL("./public", import.meta.url).toString(),
})

Para código que o Astro processa, como arquivos JavaScript e CSS importados, você pode customizar os nomes de arquivos finais utilizando entryFileNames, chunkFileNames, e assetFileNames na entrada vite.build.rollupOptions no seu arquivo astro.config.*.

astro.config.mjs
import { defineConfig } from 'astro/config'
export default defineConfig({
vite: {
build: {
rollupOptions: {
output: {
entryFileNames: 'entry.[hash].mjs',
chunkFileNames: 'chunks/chunk.[hash].mjs',
assetFileNames: 'assets/asset.[hash][extname]',
},
},
},
},
})

Isto pode ser útil caso você tenha scripts com nomes que podem ser afetados por bloqueadores de anúncios (ex. ads.js ou google-tag-manager.js).

Astro verifica arquivos de configuração antes de carregar seus outros arquivos. Portanto, você não pode utilizar import.meta.env para acessar variáveis de ambiente que foram definidas em arquivos .env. Você pode utilizar process.env em um arquivo de configuração para acessar outras variáveis de ambiente, como aquelas definidas pela CLI.

Você também pode utilizar o utilitário loadEnv do Vite para manualmente carregar arquivos .env.

astro.config.mjs
import { loadEnv } from "vite";
const { SENHA_SECRETA } = loadEnv(process.env.NODE_ENV, process.cwd(), "");

📚 Leia a referência de configuração da API do Astro para uma visão geral de todas as opções de configuração suportadas.