Comandos da Interface de Linha de Comando

Você pode utilizar a Interface de Linha de Comando (CLI) providenciada pelo Astro para desenvolver, fazer build e pré-visualizar seu projeto a partir de uma janela de terminal.

Comandos `astro`

Use a CLI ao executar um dos comandos documentados nessa página com seu gerenciador de pacotes preferido, opcionalmente seguido de algumas flags. Flags customizam o comportamento de um comando.

Um dos comandos que você vai usar com mais frequência é astro dev. Esse comando inicia o servidor de desenvolvimento e dá a você uma pré-visualização ao vivo e atualizada do seu site em um navegador conforme você trabalha:

# inicia o servidor de desenvolvimento
npx astro dev

# inicia o servidor de desenvolvimento
pnpm astro dev

# inicia o servidor de desenvolvimento
yarn astro dev

Você pode digitar astro --help no seu terminal para exibir uma lista de todos os comandos disponíveis:

npx astro --help

pnpm astro --help

yarn astro --help

A seguinte mensagem vai aparecer no seu terminal:

astro [comando] [...flags]

Comandos
                     add  Adiciona uma integração.
                   build  Faz build do seu projeto e escreve ele no disco.
                   check  Checa seu projeto por erros.
                     dev  Inicia o servidor de desenvolvimento.
                    docs  Abre a documentação no seu navegador da web.
                    info  Lista de informações sobre sua configuração atual do Astro.
                 preview  Pré-visualiza sua build localmente.
                    sync  Gera tipos de coleção de conteúdo.
               telemetry  Configura opções de telemetria.

Flags Globais
      --config <caminho>  Especifica seu arquivo de configuração.
        --root <caminho>  Especifica a pasta raiz do seu projeto.
            --site <url>  Especifica o site do seu projeto.
--base <nome-do-caminho>  Especifica a base do seu projeto.
               --verbose  Habilita o registro detalhado.
                --silent  Desabilita todos registros.
               --version  Mostra o número da versão e sai.
                  --open  Abre o aplicativo no navegador quando o servidor iniciar.
                  --help  Mostra essa mensagem de ajuda.

Scripts `package.json`

Você também pode usar scripts no package.json para versões mais curtas desses comandos. Usando um script permite você usar os mesmos comandos que você pode estar familiarizado com outros projetos, como o npm run build.

Os seguintes scripts para os comandos astro comuns (astro dev, astro build e astro preview) são adicionados pra você automaticamente quando você cria um projeto usando o assistente create astro.

Quando você segue as instruções para instalar o Astro manualmente, você é instruído a adicionar esses scripts você mesmo. Você também pode adicionar mais scripts para essa lista manualmente para qualquer comando que você usa frequentemente.

{
  "scripts": {
    "dev": "astro dev",
    "start": "astro dev",
    "build": "astro build",
    "preview": "astro preview"
  }
}

Você vai frequentemente usar esses comandos astro ou scripts que executam eles, sem nenhuma flag. Adicione flags para o comando quando você quer customizar o comportamento do comando. Por exemplo, você pode querer iniciar o servidor de desenvolvimento em uma porta diferente ou fazer a build do seu site com registros verbosos para depuração.

# executa o servidor de desenvolvimento na porta 8080 usando o script `start` no `package.json`
npm run start -- --port 8080

# faz build do seu site com registros verbosos usando o script `build` script no `package.json`
npm run build -- --verbose

(O -- a mais antes da flag --port é necessário para o npm passar suas flags para o comando astro.)

# executa o servidor de desenvolvimento na porta 8080 usando o script `start` no `package.json`
pnpm start --port 8080

# faz build do seu site com registros verbosos usando o script `build` script no `package.json`
pnpm build --verbose

# executa o servidor de desenvolvimento na porta 8080 usando o script `start` no `package.json`
yarn start --port 8080

# faz build do seu site com registros verbosos usando o script `build` script no `package.json`
yarn build --verbose

`astro dev`

Executa o servidor de desenvolvimento do Astro. Ele é um servidor HTTP local que não faz bundle de assets. Ele utiliza Hot Module Replacement (HMR) para atualizar seu navegador assim que você salva mudanças no seu editor.

Flags

Utilize essas flags para customizar o comportamento do servidor de desenvolvimento do Astro. Para flags compartilhadas com outros comandos Astro, veja flags comuns abaixo.

`--port`

Especifica em qual porta executar. Por padrão, 4321.

`--host [endereço opcional do host]`

Define em que endereços de IP o servidor de desenvolvimento deve ser escutado em (ou seja, IPs que não sejam localhost). Isso pode ser útil para testar o seu projeto em dispositivos locais como um celular durante o desenvolvimento.

--host - escuta em todos os endereços, incluindo endereços LAN e públicos.
--host [endereço-customizado] - é exposto em um endereço de IP em [endereço-customizado]

`astro build`

Faz a build do seu site para deploy. Por padrão, este comando irá gerar arquivos estáticos que serão colocados no diretório dist/. Se SSR estiver habilitado, o comando irá gerar os arquivos de servidor necessários para servir o seu website.

Flags

Utilize essas flags para customizar sua build. Para flags compartilhadas com outros comandos Astro, veja flags comuns abaixo.

`astro preview`

Inicia um servidor local para servir seu diretório dist/ estático.

Este comando é útil para pré-visualizar sua build localmente antes de fazer o deploy. Ele não é feito para ser executado em produção. Para ajuda com hospedagem para produção, veja nosso guia em como Fazer Deploy de um Website Astro.

Desde o Astro 1.5.0, astro preview também funciona para builds SSR se você utiliza um adaptador que o suporta. Atualmente, apenas o adaptador para Node suporta astro preview.

Pode ser combinado com as flags comuns documentadas abaixo.

`astro check`

Roda diagnósticos (como checar a tipagem de arquivos .astro) em seu projeto e reporta erros no console. Se algum error for encontrado durante o processo, ele será finalizado com o código 1.

Esse comando foi feito para ser usado em fluxos de trabalho de CI.

Flags

Use estas flags para customizar o comportamento do comando.

`--watch`

O comando vai observar qualquer mudança nos arquivos .astro, e vai reportar qualquer erro.

📚 Leia mais sobre o suporte para TypeScript no Astro.

`astro sync`

Adicionado em: astro@2.0.0

Gera tipos do TypeScript para todos os módulos do Astro. Ele configura um arquivo src/env.d.ts para inferência de tipos e define o módulo astro:content para a API de Coleções de Conteúdo.

`astro add`

Adiciona uma integração a sua configuração. Leia mais no guia de integrações.

`astro docs`

Abre o website da documentação do Astro diretamente do seu terminal.

`astro info`

Reporta informações úteis sobre seu ambiente do Astro atual. Útil para fornecer informações ao abrir uma issue.

astro info

Exemplo de saída:

Versão do Astro                 v2.6.6
Gerenciador de pacotes          pnpm
Plataforma                      darwin
Arquitetura                     arm64
Adaptador                       @astrojs/vercel/serverless
Integrações                     Nenhum ou não foi possível determinar.

`astro telemetry`

Define a configuração de telemetria para o usuário da CLI atual. Telemetria são dados anônimos que providenciam informações ao time do Astro sobre quais funcionalidades do Astro são mais utilizadas.

Telemetria pode ser desabilitada com o esse comando de linha de comando: a

astro telemetry disable

Telemetria pode ser posteriormente habilitada com:

astro telemetry enable

O comando clear reseta os dados de telemetria:

astro telemetry clear

Flags Comuns

`--root <caminho>`

Especifica o caminho para a raiz do projeto. Se não for especificado, o diretório de trabalho atual é assumido como a raiz.

A raiz é utilizada para encontrar o arquivo de configuração Astro.

astro --root minhaPastaRaiz/minhaPastaDoProjeto dev

`--config <caminho>`

Especifica o caminho para o arquivo de configuração relativo a raiz do projeto. Por padrão, astro.config.mjs. Use isso se você utiliza um nome diferente para o seu arquivo de configuração ou se você tem seu arquivo de configuração em outra pasta.

astro --config config/astro.config.mjs dev

`--site <url>`

Configura a opção site para seu projeto. Passar essa flag irá sobrescrever o valor de site no seu arquivo astro.config.mjs, se um existir.

`--base <nome-do-caminho>`

Adicionado em: astro@1.4.1

Configura a opção base para seu projeto. Passar essa flag irá sobrescrever o valor de base no seu arquivo astro.config.mjs, se um existir.

`--verbose`

Habilita logging verboso, que é útil para depurar um problema.

`--silent`

Habilita logging silencioso, que irá executar o servidor sem nada ser jogado ao terminal.

Flags Globais

Utilize essas flags para conseguir informação sobre a CLI astro.

`--version`

Mostra o número de versão do Astro.

`--open`

Automaticamente abre o aplicativo no navegador quando o servidor iniciar.

`--help`

Mostra a mensagem de ajuda e sai.

APIs Avançadas (Experimental)

Se você precisa de mais controle ao executar Astro, o pacote "astro" também exporta APIs para programaticamente executar os comandos da CLI.

Essas APIs são experimentais e a assinatura de suas APIs podem mudar. Quaisquer atualizações serão mencionadas no registro de mudanças do Astro e a informação abaixo irá sempre mostrar a informação atual e atualizada.

`AstroInlineConfig`

O tipo AstroInlineConfig é usado para todas as APIs de comandos abaixo. Ela se estende do tipo da configuração do Astro do usuário:

interface AstroInlineConfig extends AstroUserConfig {
  configFile?: string | false;
  mode?: "development" | "production";
  logLevel?: "debug" | "info" | "warn" | "error" | "silent";
}

`configFile`

Tipo: string | false
Padrão: undefined

Um caminho customizado para o arquivo de configuração do Astro.

Se esse valor é undefined (padrão) ou ausente, Astro irá procurar por um arquivo astro.config.(js,mjs,ts)relativo ao root e irá carregar o arquivo de configuração, se encontrado.

Se um caminho relativo é definido, ele será resolvido com base no diretório de trabalho atual.

Defina para false para desabilitar o carregamento de quaisquer arquivos de configuração.

A configuração inline passada nesse objeto irá tomar a maior prioridade ao ser combinada com a configuração do usuário carregada.

`mode`

Tipo: "development" | "production"
Padrão: "development" quando executar astro dev, "production" quando executar astro build

O modo utilizado ao fazer build do seu site para gerar um código de “desenvolvimento” ou “produção”.

`logLevel`

Tipo: "debug" | "info" | "warn" | "error" | "silent"
Padrão: "info"

O nível de registro para filtrar mensagens registradas pelo Astro.

"debug": Registre tudo, incluindo diagnósticos barulhentos de depuração.
"info": Registre mensagens informacionais, avisos e erros.
"warn": Registre avisos e erros.
"error": Registre apenas erros.
"silent": Sem registros.

`dev()`

Tipo: (inlineConfig: AstroInlineConfig) => AstroDevServer

Similar ao astro dev, ele executa o servidor de desenvolvimento do Astro.

import { dev } from "astro";

const servidorDev = await dev({
  root: "./meu-projeto",
});

// Stop the server if needed
await servidorDev.stop();

`build()`

Tipo: (inlineConfig: AstroInlineConfig) => void

Similar ao astro build, ele faz build do seu site para deploy.

import { build } from "astro";

await build({
  root: "./meu-projeto",
});

`preview()`

Tipo: (inlineConfig: AstroInlineConfig) => AstroPreviewServer

Similar ao astro preview, ele inicia um servidor local para servir seu diretório dist/ estático.

import { preview } from "astro";

const servidorPreview = await preview({
  root: "./meu-projeto",
});

// Pare o servidor se necessário
await servidorPreview.stop();

`sync()`

Tipo: (inlineConfig: AstroInlineConfig) => number

Similar ao astro sync, ele gera tipos do TypeScript para todos os módulos do Astro

import { sync } from "astro";

const codigoSaida = await sync({
  root: "./meu-projeto",
});

process.exit(codigoSaida)

Criar uma Issue no GitHub

Enviar feedback

Comandos da Interface de Linha de Comando

Comandos `astro`

Scripts `package.json`

`astro dev`

Flags

`--port`

`--host [endereço opcional do host]`

`astro build`

Flags

`astro preview`

`astro check`

Flags

`--watch`

`astro sync`

`astro add`

`astro docs`

`astro info`

`astro telemetry`

Flags Comuns

`--root <caminho>`

`--config <caminho>`

`--site <url>`

`--base <nome-do-caminho>`

`--verbose`

`--silent`

Flags Globais

`--version`

`--open`

`--help`

APIs Avançadas (Experimental)

`AstroInlineConfig`

`configFile`

`mode`

`logLevel`

`dev()`

`build()`

`preview()`

`sync()`

Comandos da Interface de Linha de Comando

Comandos astro

Scripts package.json

astro dev

Flags

--port

--host [endereço opcional do host]

astro build

Flags

astro preview

astro check

Flags

--watch

astro sync

astro add

astro docs

astro info

astro telemetry

Flags Comuns

--root <caminho>

--config <caminho>

--site <url>

--base <nome-do-caminho>

--verbose

--silent

Flags Globais

--version

--open

--help

APIs Avançadas (Experimental)

AstroInlineConfig

configFile

mode

logLevel

dev()

build()

preview()

sync()

Comandos `astro`

Scripts `package.json`

`astro dev`

`--port`

`--host [endereço opcional do host]`

`astro build`

`astro preview`

`astro check`

`--watch`

`astro sync`

`astro add`

`astro docs`

`astro info`

`astro telemetry`

`--root <caminho>`

`--config <caminho>`

`--site <url>`

`--base <nome-do-caminho>`

`--verbose`

`--silent`

`--version`

`--open`

`--help`

`AstroInlineConfig`

`configFile`

`mode`

`logLevel`

`dev()`

`build()`

`preview()`

`sync()`