Instale e Configure Astro

O comando CLI create astro é a maneira mais rápida de começar um novo projeto Astro do zero. Ele o guiará por cada etapa de configurar o seu novo projeto Astro e permitirá que você escolha alguns modelos iniciais oficiais diferentes.

Ou você pode iniciar seu projeto usando algum tema existente ou modelo inicial.

Para instalar Astro manualmente, veja nosso guia passo-a-passo de instalação manual.

Pré-requisitos

Node.js - v18.17.1, v20.3.0 ou maior. ( v19 não é suportada.)
Editor de texto - Recomendamos VS Code com nossa extensão oficial Astro.
Terminal - Astro é accessado pela interface de linha de comando (CLI).

Compatibilidade de navegador

Astro é construído com Vite que tem como alvo navegadores com suporte a JavaScript moderno por padrão. Para referência completa, você pode ver a lista de versões de navegadores atualmente suportados por Vite.

Comece um novo projeto

Instale com o assistente CLI

Execute o seguinte comando no seu terminal para iniciar o nosso útil assistente de instalação:
- npm
- pnpm
- yarn
Janela do terminal
# cria um novo projeto com npm npm create astro@latest
Janela do terminal
# cria um novo projeto com pnpm pnpm create astro@latest
Janela do terminal
# cria um novo projeto com yarn yarn create astro
Você pode executar create astro em qualquer lugar de sua máquina, então não há a necessidade de criar um novo diretório vazio para seu projeto antes de você começar. Se você não tiver um diretório vazio ainda para o seu projeto, o assistente ajudará a criá-lo automaticamente.

Se tudo correr bem, você verá uma mensagem de sucesso seguida por alguns passos recomendados. Agora que seu projeto foi criado, você pode executar cd no seu novo diretório de projeto para começar a usar Astro.
Se você pulou o passo npm install durante o assistente CLI, então certifique-se de instalar as dependências antes de continuar.
Você agora pode iniciar o servidor de desenvolvimento Astro e ver a visualizacão em tempo real do seu projeto enquanto você constrói!

Use um tema ou um modelo inicial

Você também pode começar um projeto Astro baseado em um exemplo oficial ou com a branch main de qualquer repositório GitHub passando o argumento --template ao comando create astro.

Explore nossa vitrine de temas e modelos onde você pode procurar temas para blogs, portfólios, sites de documentação, páginas iniciais e mais! Ou procure no GitHub por ainda mais projetos iniciais.

Execute o seguinte comando no seu terminal, substituindo o nome do modelo inicial oficial Astro, ou o nome de usuário e repositório no GitHub com o tema que você quer usar:

# cria um novo projeto com um exemplo oficial
npm create astro@latest -- --template <example-name>

# cria um novo projeto baseado na branch main de um repositório GitHub
npm create astro@latest -- --template <github-username>/<github-repo>

# cria um novo projeto com um exemplo oficial
pnpm create astro@latest --template <example-name>

# cria um novo projeto baseado na branch main de um repositório GitHub
pnpm create astro@latest --template <github-username>/<github-repo>

# cria um novo projeto com um exemplo oficial
yarn create astro --template <example-name>

# cria um novo projeto baseado na branch main de um repositório GitHub
yarn create astro --template <github-username>/<github-repo>

Por padrão, esse comando usará a branch main do repositório de modelo. Para usar um nome de branch diferente, passe como parte do argumento --template: <github-username>/<github-repo>#<branch>.

Responda as perguntas e siga as instruções do assistente CLI.
Você agora pode iniciar o servidor de desenvolvimento Astro e ver a visualizacão em tempo real do seu projeto enquanto você deixa ele com sua cara!

Edite seu projeto

Para fazer mudanças em seu projeto, abra a pasta do seu projeto em seu editor de código. Trabalhar no modo de desenvolvimento com o servidor de desenvolvimento rodando permite que você veja atualizações no seu site conforme você edita o código.

Você pode também personalizar aspectos do seu ambiente de desenvolvimento como configurar TypeScript ou instalar as extensões de editor oficiais Astro.

Inicie o servidor de desenvolvimento Astro

Astro vem com um servidor de desenvolvimento embutido que possui tudo que você precisa para desenvolver projetos. O comando CLI astro dev iniciará o servidor de desenvolvimento local para que você possa ver seu novo website em ação pela primeiríssima vez.

Todo modelo de projeto inicial vem com um script pré-configurado para executar astro dev por você. Depois de navegar até o diretório do seu projeto, use seu gerenciador de pacotes favorito para executar esse comando e iniciar o servidor de desenvolvimento Astro.

npm run dev

pnpm run dev

yarn run dev

Se tudo correr bem, Astro agora servirá seu projeto em http://localhost:4321/. Visite esse link no seu navegador e veja seu novo site!

Trabalhe em modo de desenvolvimento

Astro verificará por mudanças em seus arquivos em tempo real no seu diretório src/ e atualizará a prévia do seu site conforme você constrói, assim você não precisa reiniciar seu servidor quando mudanças são realizadas durante o desenvolvimento. Você será sempre capaz de ver uma versão atualizada do seu site no navegador quando o servidor de desenvolvimento estiver rodando.

Ao ver seu site no navegador, você terá acesso a barra de ferramentas de desenvolvimento Astro. Conforme você constrói, ela ajudará você a inspecionar suas ilhas, detectar problemas de acessibilidade e mais.

Se você não é capaz de abrir seu projeto no navegador depois de iniciar o servidor de desenvolvimento, volte ao terminal onde você executou o comando dev e verifique a mensagem mostrada. Ela deverá dizer se algum erro aconteceu, ou se seu projeto está sendo servido em uma URL diferente do que http://localhost:4321/.

Configure seu ambiente de desenvolvimento

Explore os guias abaixo para personalizar a sua experiência de desenvolvimento.

Configuração do Editor Personalize seu editor de código para melhorar a experiência de desenvolvedor Astro e descobrir novas funcionalidades.

Barra de Ferramentas de Desenvolvimento Explore as funcionalidades úteis da barra de ferramentas de desenvolvimento.

TypeScript no Astro

Astro vem com suporte embutido para TypeScript, que pode ajudar a prevenir erros em tempo de execução ao definir as formas de objetos e componentes no seu código.

Você não precisa escrever código TypeScript em seus projetos Astro para se beneficiar dele. Astro sempre trata o código do seu componente como TypeScript, e a Extensão VSCode Astro inferirá o quanto possível para fornecer preenchimento automático, dicas e erros em seu editor.

Leia mais sobre usar e configurar TypeScript no Astro

Construa e pré-visualize seu site

Para conferir a versão do seu site que será criada no momento de build, saia do servidor de desenvolvimento (Ctrl + C) e execute no terminal o comando de build apropriado para o seu gerenciador de pacotes:

npm run build

pnpm build

yarn run build

Astro fará a build de uma versão do seu site pronta para distribuição em uma pasta separada (dist/ por padrão) e permitirá que você assista o progresso pelo terminal. Isso alertará você sobre quaisquer erros de build no seu projeto antes de você distribuir em produção. Se o TypeScript é configurado com strict ou strictest, o script build também verificará por erros de tipo em seu projeto.

Quando a build é finalizada, execute o comando preview apropriado (como npm run preview) em seu terminal e você poderá visualizar a versão construída do seu site localmente na mesma janela de navegação de pré-visualização.

Note que isso pré-visualiza seu código que existia quando o comando build foi executado pela última vez. Isso tem a intenção de lhe dar uma prévia de como seu site parecerá quando ele for distribuído na web. Qualquer mudança futura que você realizar no seu código depois da build não será refletida na pré-visualização do seu site até que você execute o comando de build novamente.

Use (Ctrl + C) para sair da pré-visualização e execute outro comando de terminal, como reiniciar o servidor de desenvolvimento ou voltar a trabalhar no modo de desenvolvimento que fará atualizações conforme você edita para mostrar uma prévia em tempo real das mudanças no seu código.

Leia mais sobre a CLI Astro e os comandos de terminal que você usará conforme você constrói com Astro.

Distribua seu novo site

Você pode querer distribuir seu site imediatamente antes de você começar a adicionar ou mudar muito código. Isso é útil para ter uma versão mínima e funcional do seu site publicada, e pode fazer você poupar tempo e esforços futuramente diagnosticando problemas na distribuição.

Próximos passos

Successo! Agora você está pronto para começar a construir com Astro! 🥳

Aqui estão algumas coisas que recomendamos explorar a seguir. Você pode ler em qualquer ordem. Você pode até sair da nossa documentação e se divertir com seu novo projeto Astro, voltando aqui a qualquer momento que você encontrar problemas ou que tiver uma pergunta.

Explore Funcionalidades do Astro

Entenda sua base de código Aprenda mais sobre a estrutura de arquivos Astro em nosso guia de Estrutura de Projeto.

Crie coleções de conteúdo Adicione conteúdo ao seu novo site com validação frontmatter e segurança de tipos automática.

Adicione transições de visualização Crie transições de página e animações perfeitas.

Aprenda sobre Ilhas Leia sobre a arquitetura de ilhas Astro.

Faça o tutorial introdutório

Construa um blog Astro completamente funcional a partir de uma simples página em branco em nosso tutorial introdutório.

Essa é uma ótima maneira de ver como Astro funciona e guiar você pelos básicos de páginas, layouts, componentes, roteamento, ilhas e mais. Ele também inclui uma unidade opcional e amigável para iniciantes e para aqueles mais novos nos conceitos gerais de desenvolvimento web, que guiarão você em instalar as aplicações necessárias em seu computador, criar uma conta no GitHub, e distribuir seu site.

Instalação Manual

Esta explicação guiará você pelos passos de instalar manualmente e configurar um novo projeto Astro.

Se você preferir não usar nossa ferramenta CLI automática create astro, você pode configurar seu projeto por si mesmo ao seguir os passos abaixo.

Crie seu diretório

Crie um diretório vazio com o nome do seu projeto, e navegue até ele.
Janela do terminal
```
mkdir my-astro-project
cd my-astro-project
```
Uma vez que você estiver em seu novo diretório, crie seu arquivo de projeto package.json. Isso é como você gerenciará as dependências do seu projeto, incluindo Astro. Se você não é familiarizado com esse formato de arquivo, execute o seguinte comando para criar um.
- npm
- pnpm
- yarn
Janela do terminal
npm init --yes
Janela do terminal
pnpm init
Janela do terminal
yarn init --yes
Instale Astro

Primeiro, instale as dependências do projeto Astro dentro do seu projeto.

Astro deve ser instalado localmente, não globalmente. Certifique-se de que você não está executando npm install -g astro pnpm add -g astro ou yarn add global astro.
- npm
- pnpm
- yarn
Janela do terminal
npm install astro
Janela do terminal
pnpm add astro
Janela do terminal
yarn add astro
Então, substitua qualquer item gerado na seção “scripts” do seu package.json com o seguinte:
package.json
```
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1",
    "dev": "astro dev",
    "start": "astro dev",
    "build": "astro build",
    "preview": "astro preview"
  },
```
Você poderá usar esses scripts depois no guia para iniciar e rodar diferentes comandos Astro.

Crie sua primeira página

No seu editor de texto, crie um novo arquivo no seu diretório em src/pages/index.astro. Esta será a sua primeira página Astro no projeto.

Para esse guia, copie e cole o seguinte trecho de código (incluindo os traços ---) em seu novo arquivo:

---
// Bem-vindo ao Astro! Todo código entre esses três traços
// é o "frontmatter de componente". Ele nunca executa no navegador.
console.log('Isso executa em seu terminal, não no navegador!');
---
<!-- Abaixo está seu "modelo de componente". É apenas HTML, mas com
    um toque de mágica para ajudar você a construir modelos excelentes. -->
<html>
  <body>
    <h1>Olá, Mundo!</h1>
  </body>
</html>
<style>
  h1 {
    color: orange;
  }
</style>

Crie seu primeiro recurso estático

Você também desejará criar um novo diretório public/ para armazenar seus recursos estáticos. Astro sempre incluirá esses recursos em sua build final para que você possa referenciá-los com segurança dentro dos seus modelos de componente.

No seu editor de texto, crie um novo arquivo no seu diretório em public/robots.txt. robots.txt é um arquivo simples que a maioria dos sites incluirá para falar aos robôs de busca, como o Google, sobre como tratar seu site.

Para esse guia, copie e cole o seguinte trecho de código em seu novo arquivo:
public/robots.txt
```
# Exemplo: Permita que todos os robôs verifiquem e indexem seu site.
# Sintaxe completa: https://developers.google.com/search/docs/advanced/robots/create-robots-txt
User-agent: *
Allow: /
```
Crie astro.config.mjs

Astro é configurado usando astro.config.mjs. Este arquivo é opcional se você não quiser configurar o Astro, mas você pode querer criá-lo agora.

Crie astro.config.mjs na raiz do seu projeto, e copie e cole o código abaixo nele:
astro.config.mjs
```
import { defineConfig } from 'astro/config';

// https://astro.build/config
export default defineConfig({});
```
Se você desejar incluir componentes de framework UI como React, Svelte, etc. ou usar outras ferramentas como Tailwind ou Partytown em seu projeto, aqui é onde você importará e configurará as integrações manualmente.

Leia a API de referência de configuração Astro para maiores informações.
Adicione suporte TypeScript

TypeScript é configurado usando tsconfig.json. Mesmo que você não escreva código TypeScript, esse arquivo será importante para que ferramentas como Astro e VS Code saibam como entender seu projeto. Algumas funcionalidades (como npm package imports) não são completamente suportados no editor sem um arquivo tsconfig.json.

Se você pretende escrever código TypeScript, usar o modelo Astro strict ou strictest é recomendado. Você pode ver e comparar as três configurações de modelo em astro/tsconfigs/.

Crie tsconfig.json na raiz do seu projeto, e copie e cole o código abaixo nele. (Você pode usar base, strict, ou strictest para seu modelo TypeScript):
tsconfig.json
```
{
  "extends": "astro/tsconfigs/base"
}
```
Leia o guia de instalção TypeScript Astro para mais informações.
Próximos Passos

Se você seguiu os passos acima, o diretório do seu projeto deve estar parecendo com o seguinte:
- Directorynode_modules/
  - …
- Directorypublic/
  - robots.txt
- Directorysrc/
  - Directorypages/
    index.astro
- astro.config.mjs
- package-lock.json ou yarn.lock, pnpm-lock.yaml, etc.
- package.json
- tsconfig.json
Você agora pode iniciar o servidor de desenvolvimento Astro e ver uma prévia em tempo real do seu projeto enquanto você constrói!

Contribute

Community