diff --git a/src/content/docs/pt-br/reference/cli-reference.mdx b/src/content/docs/pt-br/reference/cli-reference.mdx new file mode 100644 index 0000000000000..f36b528251ffb --- /dev/null +++ b/src/content/docs/pt-br/reference/cli-reference.mdx @@ -0,0 +1,482 @@ +--- +title: Comandos da CLI +i18nReady: true +--- +import Since from '~/components/Since.astro'; +import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro' +import ReadMore from '~/components/ReadMore.astro' + +Você pode usar a Interface de Linha de Comando (CLI) fornecida pelo Astro para desenvolver, compilar e visualizar seu projeto a partir de uma janela de terminal. + +### Comandos `astro` + +Use a CLI executando um dos **comandos** documentados nesta página com seu gerenciador de pacotes escolhido, opcionalmente seguido por quaisquer **flags**. As flags customizam o comportamento de um comando. + +Um dos comandos que você usará com mais frequência é `astro dev`. Este comando inicia o servidor de desenvolvimento e oferece uma vizualização ao vivo e atualizada do seu site em um navegador enquanto você trabalha: + + + + ```shell + # inicia o servidor de desenvolvimento + npx astro dev + ``` + + + ```shell + # inicia o servidor de desenvolvimento + pnpm astro dev + ``` + + + ```shell + # 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: + + + + ```shell + npx astro --help + ``` + + + ```shell + pnpm astro --help + ``` + + + ```shell + yarn astro --help + ``` + + + +A seguinte mensagem será exibida no seu terminal: + +```bash +astro [command] [...flags] + +Commands + add Add an integration. + build Build your project and write it to disk. + check Check your project for errors. + create-key Create a cryptography key + dev Start the development server. + docs Open documentation in your web browser. + info List info about your current Astro setup. + preview Preview your build locally. + sync Generate TypeScript types for all Astro modules. + preferences Configure user preferences. + telemetry Configure telemetry settings. + +Global Flags + --config Specify your config file. + --root Specify your project root folder. + --site Specify your project site. +--base Specify your project base. + --verbose Enable verbose logging. + --silent Disable all logging. + --version Show the version number and exit. + --help Show this help message. +``` + + +Você pode adicionar a flag `--help` após qualquer comando para obter uma lista de todas as flags disponíveis para esse comando. + + + + ```shell + # obtém uma lista de todas as flags para o comando `dev` + npm run dev -- --help + ``` + + + ```shell + # obtém uma lista de todas as flags para o comando `dev` + pnpm dev --help + ``` + + + ```shell + # obtém uma lista de todas as flags para o comando `dev` + yarn dev --help + ``` + + + +A seguinte mensagem será exibida no seu terminal: + +```bash +astro dev [...flags] + +Flags + --port Specify which port to run on. Defaults to 4321. + --host Listen on all addresses, including LAN and public addresses. +--host Expose on a network IP address at + --open Automatically open the app in the browser on server start + --force Clear the content layer cache, forcing a full rebuild. + --help (-h) See all available flags. +``` + +:::note +O `--` extra antes de qualquer flag é necessário para o `npm` passar suas flags para o comando `astro`. +::: + +### Scripts do `package.json` + +Você também pode usar scripts no `package.json` para versões mais curtas desses comandos. Usar um script permite que você utilize os mesmos comandos com os quais você pode estar familiarizado em outros projetos, como `npm run build`. + +Os seguintes scripts para os comandos `astro` mais comuns (`astro dev`, `astro build` e `astro preview`) são adicionados automaticamente quando você cria um projeto usando [o assistente `create astro`](/pt-br/install-and-setup/). + +Quando você segue as instruções para [instalar o Astro manualmente](/pt-br/install-and-setup/#manual-setup), você é instruído a adicionar esses scripts você mesmo. Você também pode adicionar mais scripts a esta lista manualmente para quaisquer comandos que você usa com frequência. + +```json title="package.json" +{ + "scripts": { + "dev": "astro dev", + "build": "astro build", + "preview": "astro preview" + } +} +``` + +Você frequentemente usará esses comandos `astro`, ou os scripts que os executam, sem quaisquer flags. Adicione flags ao comando quando quiser customizar o comportamento do comando. Por exemplo, você pode desejar iniciar o servidor de desenvolvimento em uma porta diferente, ou compilar seu site com logs detalhados para depuração. + + + + ```shell + # executa o servidor de desenvolvimento na porta 8080 usando o script `dev` no `package.json` + npm run dev -- --port 8080 + + # compila seu site com logs detalhados usando o script `build` no `package.json` + npm run build -- --verbose + ``` + + + ```shell + # executa o servidor de desenvolvimento na porta 8080 usando o script `dev` no `package.json` + pnpm dev --port 8080 + + # compila seu site com logs detalhados usando o script `build` no `package.json` + pnpm build --verbose + ``` + + + ```shell + # executa o servidor de desenvolvimento na porta 8080 usando o script `dev` no `package.json` + yarn dev --port 8080 + + # compila seu site com logs detalhados usando o script `build` no `package.json` + yarn build --verbose + ``` + + + +## `astro dev` + +Executa o servidor de desenvolvimento do Astro. Este é um servidor HTTP local que não empacota assets. Ele usa Hot Module Replacement (HMR) para atualizar seu navegador à medida que você salva alterações no seu editor. + +Os seguintes atalhos de teclado podem ser usados no terminal onde o servidor de desenvolvimento do Astro está sendo executado: + +- `s + enter` para sincronizar os dados da camada de conteúdo (conteúdo e tipos). +- `o + enter` para abrir seu site Astro no navegador. +- `q + enter` para encerrar o servidor de desenvolvimento. + +## `astro build` + +Compila seu site para implantação. Por padrão, isso irá gerar arquivos estáticos e colocá-los em um diretório `dist/`. Se alguma rota for [renderizada sob demanda](/pt-br/guides/on-demand-rendering/), isso irá gerar os arquivos de servidor necessários para servir seu site. + +### Flags + +O comando aceita [flags comuns](#flags-comuns) e as seguintes flags adicionais: + +#### `--devOutput` + +

+ +Gera uma compilação baseada em desenvolvimento semelhante ao código transformado em `astro dev`. Isso pode ser útil para testar problemas específicos de compilação com informações de depuração adicionais incluídas. + +## `astro preview` + +Inicia um servidor local para servir o conteúdo do seu diretório estático (`dist/` por padrão) criado ao executar `astro build`. + +Este comando permite que você visualize seu site localmente [após compilá-lo](#astro-build) para capturar quaisquer erros na saída da sua compilação antes de implantá-lo. Ele não foi projetado para ser executado em produção. Para ajuda com hospedagem em produção, confira nosso guia sobre [Implantando um Site Astro](/pt-br/guides/deploy/). + +Desde o Astro 1.5.0, o [adaptador Node](/pt-br/guides/integrations-guide/node/) suporta `astro preview` para compilações geradas com renderização sob demanda. + +Pode ser combinado com as [flags comuns](#flags-comuns) documentadas abaixo. + +## `astro check` + +Executa diagnósticos (como verificação de tipos dentro de arquivos `.astro`) no seu projeto e reporta erros no console. Se algum erro for encontrado, o processo será encerrado com o código **1**. + +Este comando é destinado a ser usado em fluxos de trabalho de CI. + +

Flags

+ +Use essas flags para customizar o comportamento do comando. + +#### `--watch` + +O comando observará quaisquer alterações no seu projeto e reportará quaisquer erros. + +#### `--root ` + +Especifica um diretório raiz diferente para verificar. Usa o diretório de trabalho atual por padrão. + +#### `--tsconfig ` + +Especifica um arquivo `tsconfig.json` para usar manualmente. Se não for fornecido, o Astro tentará encontrar uma configuração ou inferir a configuração do projeto automaticamente. + +#### `--minimumFailingSeverity ` + +Especifica a severidade mínima necessária para encerrar com um código de erro. Padrão é `error`. + +Por exemplo, executar `astro check --minimumFailingSeverity warning` fará com que o comando encerre com um erro se algum aviso for detectado. + +#### `--minimumSeverity ` + +Especifica a severidade mínima para saída. Padrão é `hint`. + +Por exemplo, executar `astro check --minimumSeverity warning` mostrará erros e avisos, mas não dicas. + +#### `--preserveWatchOutput` + +Especifica para não limpar a saída entre verificações quando estiver no modo de observação. + +#### `--noSync` + +Especifica para não executar `astro sync` antes de verificar o projeto. + +Leia mais sobre [verificação de tipos no Astro](/pt-br/guides/typescript/#type-checking). + +## `astro sync` + +

+ +:::tip +Executar `astro dev`, `astro build` ou `astro check` também executará o comando `sync`. +::: + +Gera tipos TypeScript para todos os módulos Astro. Isso configura um [arquivo `.astro/types.d.ts`](/pt-br/guides/typescript/#setup) para inferência de tipos e define módulos para recursos que dependem de tipos gerados: +- O módulo `astro:content` para a [API de Coleções de Conteúdo](/pt-br/guides/content-collections/). +- O módulo `astro:db` para [Astro DB](/pt-br/guides/astro-db/). +- O módulo `astro:env` para [Astro Env](/pt-br/guides/environment-variables/). +- O módulo `astro:actions` para [Astro Actions](/pt-br/guides/actions/) + +## `astro add` + +Adiciona uma integração à sua configuração. Leia mais no [guia de integrações](/pt-br/guides/integrations-guide/#automatic-integration-setup). + +## `astro docs` + +Abre o site de Documentação do Astro diretamente do terminal. + +## `astro info` + +Reporta informações úteis sobre seu ambiente Astro atual. Útil para fornecer informações ao abrir uma issue. + +```shell +astro info +``` + +Exemplo de saída: + +``` +Astro v5.14.1 +Vite v6.3.6 +Node v22.17.1 +System macOS (arm64) +Package Manager npm +Output static +Adapter none +Integrations @astrojs/starlight (v0.35.3) +``` + +## `astro preferences` + +Gerencie preferências de usuário com o comando `astro preferences`. As preferências de usuário são específicas para usuários individuais do Astro, diferentemente do arquivo `astro.config.mjs` que altera o comportamento para todos que trabalham em um projeto. + +As preferências de usuário têm escopo para o projeto atual por padrão, armazenadas em um arquivo local `.astro/settings.json`. + +Usando a flag `--global`, as preferências de usuário também podem ser aplicadas a todos os projetos Astro na máquina atual. As preferências de usuário globais são armazenadas em um local específico do sistema operacional. + +

Preferências disponíveis

+ +- `devToolbar` — Habilita ou desabilita a barra de ferramentas de desenvolvimento no navegador. (Padrão: `true`) +- `checkUpdates` — Habilita ou desabilita a verificação automática de atualizações para a CLI do Astro. (Padrão: `true`) + +O comando `list` imprime as configurações atuais de todas as preferências de usuário configuráveis. Ele também suporta uma saída `--json` legível por máquina. + +```shell +astro preferences list +``` + +Exemplo de saída do terminal: + +| Preference | Value | +| ------------------------ | ----- | +| devToolbar.enabled | true | +| checkUpdates.enabled | true | + + +Você pode usar `enable`, `disable` ou `reset` para configurar preferências com seus valores padrão. + +Por exemplo, para desabilitar a devToolbar em um projeto Astro específico: + +```shell +astro preferences disable devToolbar +``` + +Para desabilitar a devToolbar em todos os projetos Astro na máquina atual: + +```shell +astro preferences disable --global devToolbar +``` + +A devToolbar pode ser habilitada posteriormente com: + +```shell +astro preferences enable devToolbar +``` + +O comando `reset` redefine uma preferência para seu valor padrão: + +```shell +astro preferences reset devToolbar +``` + +## `astro telemetry` + +Define a configuração de telemetria para o usuário atual da CLI. A telemetria são dados anônimos que fornecem à equipe do Astro insights sobre quais recursos do Astro são mais frequentemente usados. Para mais informações, consulte [a página de telemetria do Astro](https://astro.build/telemetry/). + +A telemetria pode ser desabilitada com este comando da CLI: + +```shell +astro telemetry disable +``` + +A telemetria pode ser reabilitada posteriormente com: + +```shell +astro telemetry enable +``` + +O comando `reset` redefine os dados de telemetria: + +```shell +astro telemetry reset +``` + +:::tip[Quer desabilitar a telemetria em ambientes de CI?] +Adicione o comando `astro telemetry disable` aos seus scripts de CI ou defina a variável de ambiente `ASTRO_TELEMETRY_DISABLED`. +::: + +## `astro create-key` + +Gera uma chave para criptografar props passadas para server islands. + +```shell +astro create-key +``` + +Defina esta chave como a variável de ambiente `ASTRO_KEY` (por exemplo, em um arquivo `.env`) e inclua-a nas configurações de compilação do seu CI/CD ou host quando você precisar [de uma chave de criptografia constante para suas server islands](/pt-br/guides/server-islands/#reusing-the-encryption-key) para situações como implantações contínuas, hospedagem multi-região ou um CDN que armazena em cache páginas contendo server islands. + +## Flags comuns + +### `--root ` + +Especifica o caminho para a raiz do projeto. Se não especificado, o diretório de trabalho atual é assumido como a raiz. + +A raiz é usada para encontrar o arquivo de configuração do Astro. + +```shell +astro --root myRootFolder/myProjectFolder dev +``` + +### `--config ` + +Especifica o caminho para o arquivo de configuração relativo à raiz do projeto. Padrão é `astro.config.mjs`. Use isto se você usar um nome diferente para seu arquivo de configuração ou tiver seu arquivo de configuração em outra pasta. + +```shell +astro --config config/astro.config.mjs dev +``` + +### `--force ` + +

+ +Limpa o [cache da camada de conteúdo](/pt-br/guides/content-collections/#defining-the-collection-loader), forçando uma reconstrução completa. + +### `--mode ` + +

+ +Configura o [`mode`](/pt-br/reference/programmatic-reference/#mode) em linha para seu projeto. + +### `--outDir ` + +

+ +Configura o [`outDir`](/pt-br/reference/configuration-reference/#outdir) para seu projeto. Passar esta flag substituirá o valor `outDir` no seu arquivo `astro.config.mjs`, se existir. + +### `--site ` + +Configura o [`site`](/pt-br/reference/configuration-reference/#site) para seu projeto. Passar esta flag substituirá o valor `site` no seu arquivo `astro.config.mjs`, se existir. + +### `--base ` + +

+ +Configura o [`base`](/pt-br/reference/configuration-reference/#base) para seu projeto. Passar esta flag substituirá o valor `base` no seu arquivo `astro.config.mjs`, se existir. + +### `--port ` + +Especifica em qual porta executar o servidor de desenvolvimento e o servidor de prévia. Padrão é `4321`. + +### `--host [optional host address]` + +Define quais endereços IP de rede o servidor de desenvolvimento e o servidor de prévia devem escutar (ou seja, IPs não-localhost). Isso pode ser útil para testar 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 ` — expõe em um endereço IP de rede em `` + +:::caution +Não use a flag `--host` para expor o servidor de desenvolvimento e o servidor de prévia em um ambiente de produção. Os servidores são projetados apenas para uso local durante o desenvolvimento do seu site. +::: + +### `--allowed-hosts` + +

+ +Especifica os nomes de host aos quais o Astro tem permissão para responder nos modos `dev` ou `preview`. Pode receber uma lista separada por vírgulas de nomes de host ou `true` para permitir qualquer nome de host. + +Consulte [o recurso `allowedHosts` do Vite](https://vite.dev/config/server-options.html#server-allowedhosts) para mais informações, incluindo implicações de segurança ao permitir nomes de host. + +### `--verbose` + +Habilita logs detalhados, o que é útil ao depurar um problema. + +### `--silent` + +Habilita logs silenciosos, que executará o servidor sem qualquer saída no console. + +### `--open` + +Abre automaticamente o aplicativo no navegador ao iniciar o servidor. Pode receber uma string de URL completa (por exemplo, `--open http://example.com`) ou um pathname (por exemplo, `--open /about`) para especificar a URL a ser aberta. + +## Flags globais + +Use essas flags para obter informações sobre a CLI `astro`. + +### `--version` + +Imprime o número da versão do Astro e encerra. + +### `--help` + +Imprime a mensagem de ajuda e encerra.