import { Tabs, TabItem, FileTree, CardGrid, LinkCard, Steps } from '@astrojs/starlight/components'; import ReadMore from '~/components/ReadMore.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.

:::tip[Prévias online] Você prefere experimentar Astro em seu navegador? Visite astro.new para navegar por nossos modelos iniciais e comece um novo projeto Astro sem mesmo sair do seu navegador. :::

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

<Tabs> <TabItem label="npm"> ```shell # cria um novo projeto com npm npm create astro@latest ``` </TabItem> <TabItem label="pnpm"> ```shell # cria um novo projeto com pnpm pnpm create astro@latest ``` </TabItem> <TabItem label="yarn"> ```shell # cria um novo projeto com yarn yarn create astro ``` </TabItem> </Tabs> 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.

2. Se você pulou o passo npm install durante o assistente CLI, então certifique-se de instalar as dependências antes de continuar.

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

2. 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 baseado na branch main de um repositório GitHub

   npm create astro@latest -- --template /

   </TabItem> <TabItem label="pnpm"> ```shell # 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 baseado na branch main de um repositório GitHub

   yarn create astro --template /

   </TabItem> </Tabs> 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>`.

3. Responda as perguntas e siga as instruções do assistente CLI.

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

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.

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:

<Tabs> <TabItem label="npm"> ```shell npm run build ``` </TabItem> <TabItem label="pnpm"> ```shell pnpm build ``` </TabItem> <TabItem label="yarn"> ```shell yarn run build ``` </TabItem> </Tabs>

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

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 um diretório vazio com o nome do seu projeto, e navegue até ele. ```bash 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. <Tabs> <TabItem label="npm"> ```shell npm init --yes ``` </TabItem> <TabItem label="pnpm"> ```shell pnpm init ``` </TabItem> <TabItem label="yarn"> ```shell yarn init --yes ``` </TabItem> </Tabs>

2. Instale Astro

Primeiro, instale as dependências do projeto Astro dentro do seu projeto. :::note[Importante] 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`. ::: <Tabs> <TabItem label="npm"> ```shell npm install astro ``` </TabItem> <TabItem label="pnpm"> ```shell pnpm add astro ``` </TabItem> <TabItem label="yarn"> ```shell yarn add astro ``` </TabItem> </Tabs> Então, substitua qualquer item gerado na seção "scripts" do seu `package.json` com o seguinte: ```json title="package.json" del={2} ins={3-6} "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.

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: ```astro title="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 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: ```diff title="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: ```js title="astro.config.mjs" import { defineConfig } from 'astro/config'; // https://astro.build/config export default defineConfig({}); ``` Se você desejar incluir [componentes de framework UI](/pt-br/guides/framework-components/) 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](/pt-br/guides/integrations-guide/). Leia a [API de referência de configuração](/pt-br/reference/configuration-reference/) Astro para maiores 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 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/](https://github.com/withastro/astro/blob/main/packages/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): ```json title="tsconfig.json" "base" { "extends": "astro/tsconfigs/base" } ``` Leia o [guia de instalção TypeScript](/pt-br/guides/typescript/#configuração) 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: <FileTree> - node_modules/ - public/ - robots.txt - src/ - pages/ - index.astro - astro.config.mjs - package-lock.json ou `yarn.lock`, `pnpm-lock.yaml`, etc. - package.json - tsconfig.json </FileTree>

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!