configuring-astro.mdx

title	i18nReady
Configurando Astro	true

import ReadMore from '~/components/ReadMore.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.

O Arquivo de Configuração Astro

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:

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

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

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.

# 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.

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

IntelliSense da Configuração

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({
  // suas opções 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} */ {
  // suas opções de configuração aqui...
  // https://docs.astro.build/pt-br/reference/configuration-reference/
}

Referenciando Arquivos Relativos

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({
  // Resulta no diretório "./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({
  // Resulta no diretório "./foo" em seu diretório de trabalho atual
  root: 'foo',
  // Resulta no diretório "./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({
  // Resulta no diretório "./foo" relativo a este arquivo de configuração.
  root: new URL("./foo", import.meta.url).toString(),
  // Resulta no diretório "./foo/public" relativo a este arquivo de configuração.
  publicDir: new URL("./public", import.meta.url).toString(),
})

:::note Propriedades específicas do Vite de import.meta, como import.meta.env ou import.meta.glob, não são acessíveis em seu arquivo de configuração. Nós recomendamos alternativas como dotenv ou fast-glob para esses respectivos casos de uso. Adicionalmente, nomes de caminho alternativos do tsconfig não serão resolvidos. Use caminhos relativos nestes arquivos para importar módulos. :::

Customizando Nomes de Arquivos Finais

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).

Variáveis de Ambiente

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.

:::note O pnpm não permite você importar módulos que não estão diretamente instalados no seu projeto. Se você está usando pnpm, você terá que instalar vite para usar o utilitário loadEnv.

pnpm add vite --save-dev

:::

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

Referência de Configuraçã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.