Pular para o conteúdo

Instalar 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 configuração do seu novo projeto Astro e permitirá que você escolha entre alguns modelos iniciais oficiais diferentes.

Você também pode executar o comando CLI com a flag --template para iniciar seu projeto usando qualquer tema ou modelo inicial existente. Explore nossa vitrine de temas e modelos iniciais onde você pode navegar por temas para blogs, portfólios, sites de documentação, páginas iniciais e mais!

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

Pré-requisitos

Seção intitulada “Pré-requisitos”
  • Node.js - v22.12.0 ou superior. Versões de número ímpar como v23 não são suportadas.
  • Editor de texto - Recomendamos o VS Code com a nossa extensão oficial do Astro.
  • Terminal - Astro é acessado pela sua interface de linha de comando (CLI).

Compatibilidade de navegadores

Seção intitulada “Compatibilidade de navegadores”

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

Instale a partir do assistente CLI

Seção intitulada “Instale a partir do assistente CLI”

Você pode executar create astro em qualquer lugar da sua máquina, portanto não há necessidade de criar um novo diretório vazio para seu projeto antes de começar. Se você ainda não tiver um diretório vazio para seu novo projeto, o assistente ajudará a criar um para você automaticamente.

  1. Execute o seguinte comando no seu terminal para iniciar o assistente de instalação:

    Terminal window
    # cria um novo projeto com npm
    npm create astro@latest

    Se tudo correr bem, você verá uma mensagem de sucesso seguida por alguns passos recomendados.

  2. Agora que seu projeto foi criado, você pode executar cd para entrar no diretório do seu novo projeto para começar a usar o Astro.

  3. Se você pulou o passo “Instalar dependências?” durante o assistente CLI, então certifique-se de instalar as dependências antes de continuar.

    Terminal window
    npm install

  4. Você agora pode iniciar o servidor de desenvolvimento do Astro e ver a visualizacão em tempo real do seu projeto enquanto constrói!

Flags de instalação da CLI

Seção intitulada “Flags de instalação da CLI”

Você pode executar o comando create astro com flags adicionais para personalizar o processo de configuração (por exemplo, respondendo “sim” a todas as perguntas, pulando a animação do Houston) ou o seu novo projeto (por exemplo, instalando o git ou não, adicionando integrações).

Veja todas as flags disponíveis para o comando create astro.

Adicionar integrações

Seção intitulada “Adicionar integrações”

Você pode iniciar um novo projeto Astro e instalar quaisquer integrações oficiais (EN) ou integrações da comunidade que suportem o comando astro add ao mesmo tempo, passando o argumento --add para o comando create astro.

Execute o seguinte comando no seu terminal, substituindo por qualquer integração que suporte o comando astro add:

Terminal window
# cria um novo projeto com React e Partytown
npm create astro@latest -- --add react --add partytown

Usar um tema ou modelo inicial

Seção intitulada “Usar um tema ou modelo inicial”

Você pode iniciar um novo projeto Astro baseado em um exemplo oficial ou na branch main de qualquer repositório do GitHub passando o argumento --template para o comando create astro.

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

Terminal window
# cria um novo projeto com um exemplo oficial
npm create astro@latest -- --template <nome-do-exemplo>


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

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

Configuração Manual

Seção intitulada “Configuração Manual”

Este guia o guiará pelas etapas para instalar e configurar manualmente um novo projeto Astro.

Se você preferir não usar nossa ferramenta create astro automática no CLI, poderá configurar seu projeto por conta própria seguindo o guia abaixo.

  1. Crie seu diretório

    Crie um diretório vazio com o nome do seu projeto e navegue até ele.

    Terminal window
    mkdir meu-projeto-astro
    cd meu-projeto-astro

    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.

    Terminal window
    npm init --yes

  2. Instale Astro

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

    Terminal window
    npm install 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",
        "build": "astro build",
        "preview": "astro preview"
      },
    }

    Você usará esses scripts depois no guia para iniciar e rodar diferentes comandos Astro.

  3. 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:

    src/pages/index.astro
    ---
    // 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>

  4. Crie seu primeiro recurso estático

    Você também desejará criar um 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: /

  5. 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 (EN) como React, Svelte, etc. ou usar outras ferramentas como MDX ou Partytown em seu projeto, aqui é onde você importará e configurará as integrações manualmente (EN).

    Leia a API de referência de configuração (EN) Astro para mais informações.

  6. 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 importações de pacotes npm) 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 (EN) Astro para mais informações.

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

  8. Você agora pode iniciar o servidor de desenvolvimento Astro e ver uma prévia em tempo real do seu projeto enquanto você constrói!

Contribua Comunidade Patrocine