1  O Laboratório nas Nuvens

Seja muito bem-vindo à sua primeira jornada prática no desenvolvimento web moderno!

Se você já tentou programar em computadores de laboratório — como os do IFPI —, provavelmente conhece a dor de cabeça tradicional: computadores compartilhados, restrições de administrador, sistemas com congelamento de disco (Deep Freeze) ou versões desatualizadas de softwares que quebram o código antes mesmo de você começar.

Neste livro, nós adotamos uma postura diferente e alinhada às práticas da indústria de tecnologia: não instalaremos nada nas máquinas físicas do laboratório. Nosso ambiente completo de desenvolvimento — incluindo editor de código, ferramentas de linha de comando, interpretadores e servidores — rodará inteiramente na nuvem por meio do GitHub Codespaces.

Isso significa que o seu código, suas configurações e seu fluxo de trabalho estarão sempre salvos e acessíveis de qualquer computador com acesso à internet e um navegador web.

Nossa missão ao longo deste livro é desenvolver o portal oficial da TED System, cujo lema é entregar a tecnologia que evolui com o seu negócio, desenvolvendo soluções de software personalizadas, seguras e escaláveis. Neste primeiro capítulo, você dará o pontapé inicial estruturando o projeto e dominando as ferramentas essenciais de trabalho.

1.1 Como copiar o código

Este livro foi feito para a prática. Na versão HTML, sempre utilize o botão de copiar presente no canto superior direito de cada bloco de código para levá-lo ao seu projeto. A versão em PDF serve como material de leitura e estudo.

Lembre-se: os comandos de terminal não levam o cifrão inicial ($) e devem ser copiados um por linha. As saídas de terminal geradas por esses comandos são marcadas de forma diferente e servem apenas para você conferir se o resultado na sua tela está correto; você notará que elas nem possuem o botão de cópia no livro digital.

1.2 Criando o Repositório no GitHub

O Git é o sistema de controle de versão mais utilizado no mundo, e o GitHub é a plataforma na nuvem onde armazenamos nossos repositórios e colaboramos em equipe. Todo projeto profissional nasce de um repositório.

Vamos criar a casa digital do nosso projeto:

1. Acesse o GitHub e faça login na sua conta pessoal.
2. No canto superior direito da página, clique no ícone + e selecione New repository (Novo repositório).
3. Na tela de criação, preencha os campos com os seguintes dados:
   • Repository name: digite ted-system-site (utilize exatamente este nome, em letras minúsculas e separado por hífen).
   • Description (opcional): Website institucional da TED System construído com Astro.
   • Choose visibility: deixe selecionada a opção Public (Público). O repositório público facilita o acesso gratuito ao Codespaces e simplificará o nosso futuro deploy no Cloudflare Pages.
   • Add README: deixe o botão ativado (On). Essa opção cria imediatamente um arquivo inicial (README.md), permitindo inicializar a branch principal (main) sem complicações.
4. Role a página e clique no botão verde Create repository (Criar repositório).

Figura 1.1: Formulário de criação de um novo repositório no GitHub

Pronto! Em poucos segundos, sua página será recarregada exibindo o repositório recém-criado.

DicaPor que adicionar o arquivo README?

O arquivo README.md funciona como o cartão de visitas do seu projeto. Além de explicar o que o projeto faz para outros desenvolvedores, criá-lo no momento inicial garante que o repositório não nasça vazio, o que permite criar um Codespace com apenas um clique!

1.3 Inicializando o GitHub Codespaces

Agora que temos o repositório, vamos iniciar nossa estação de trabalho. Esqueça instaladores do Node.js, configurações de variáveis de ambiente no Windows ou permissões de administrador: tudo o que você precisa já está pronto para uso nos servidores do GitHub.

1. Na página principal do repositório ted-system-site, localize o botão verde <> Code.
2. Clique na aba Codespaces (ao lado de Local).
3. Clique no botão verde Create codespace on main (Criar codespace na main).

Figura 1.2: Aba Codespaces no botão Code do GitHub com o botão Create codespace on main em destaque

Uma nova aba do navegador será aberta. Nos bastidores, o GitHub está provisionando um contêiner Linux dedicado para você com o Visual Studio Code pronto na interface web.

Em menos de um minuto, você verá a interface completa do VS Code rodando diretamente no navegador: com árvore de arquivos à esquerda, área de edição ao centro e barra de ferramentas integrada.

DicaLiberdade total para estudar

Se a máquina do laboratório do IFPI reiniciar, acabar a energia ou você precisar continuar os estudos em casa ou na biblioteca, basta abrir o navegador, acessar o repositório no GitHub e reabrir o seu Codespace. Tudo estará exatamente onde você parou.

1.4 Conhecendo o Terminal Integrado e o Comando pwd

Desenvolvedores profissionais não fogem da linha de comando; eles a utilizam como ferramenta diária de produtividade. No Codespaces, temos acesso a um terminal Linux completo.

1.4.1 Abrindo o Terminal

Se o terminal integrado ainda não estiver visível na parte inferior da tela:

• Pressione o atalho de teclado Ctrl + ` (ou Ctrl + ' dependendo do layout do seu teclado);
• Ou clique no ícone de menu principal (as três barrinhas horizontais no canto superior esquerdo), navegue até Terminal e clique em Novo Terminal (New Terminal).

O editor web carrega também um painel lateral direito de Chat com IA. Você pode fechar esse painel de Chat, pois não utilizaremos essa ferramenta durante as atividades deste livro.

Figura 1.3: Interface do GitHub Codespaces com o painel de arquivos à esquerda e o terminal integrado visível na parte inferior

Uma janela com o prompt de comando aparecerá. Ela se parece com isto:

@seu-usuario ➜ /workspaces/ted-system-site (main) $ 

O caractere $ (cifrão) indica que o terminal está pronto para receber suas ordens. Lembre-se de não copiar esse caractere nem o texto anterior a ele ao executar os comandos do livro.

1.4.2 O Comando pwd

Vamos executar nosso primeiro comando. Execute no terminal e tecle Enter:

pwd

O comando pwd é um acrônimo para print working directory (imprimir diretório de trabalho) e serve para mostrar em qual pasta do sistema operacional estamos trabalhando no momento. Você pode aprender mais sobre este e outros comandos básicos na documentação de linha de comando do Ubuntu.

A resposta exibida será:

/workspaces/ted-system-site

Isso confirma que o seu terminal está operando diretamente na raiz do projeto ted-system-site, dentro da estrutura de diretórios do Codespaces. É aí que todos os arquivos do site serão criados e manipulados.

1.4.3 Verificando a Versão do Node.js

O Astro necessita do interpretador Node.js para executar o servidor de desenvolvimento e compilar as páginas estáticas. No GitHub Codespaces, a imagem padrão já inclui o Node.js pronto para uso.

Vamos inspecionar a versão instalada executando:

node --version

v24.21.0

O comando node executa o Node.js, e a opção --version pede que ele mostre sua versão atual (documentação oficial do Node.js). A saída exibida confirmará a versão ativa (como v24.21.0 no exemplo acima). Dependendo de quando você criar seu Codespace, o número exato pode variar, e isso é normal. O importante é que a versão seja igual ou superior à exigida estritamente pelo Astro, que é a versão 22.12.0.

No próximo capítulo, logo após inicializarmos os arquivos do framework com o instalador do Astro, criaremos um arquivo .node-version. Ele não serve para o Codespaces (que já tem sua versão configurada e funcionando), mas informará à plataforma de publicação (Cloudflare Pages) exatamente qual versão do Node.js deverá ser usada durante a compilação do nosso site.

1.5 O Ciclo Básico de Salvamento no Git

Com o ambiente pronto e o terminal aberto, vamos aprender a rotina fundamental de qualquer desenvolvedor: o ciclo de salvamento no Git.

Diferente de um editor de texto comum que salva tudo automaticamente na nuvem sem histórico, o Git registra cada versão intencional do seu projeto. Esse fluxo funciona em três etapas essenciais:

1. git add: Seleciona quais arquivos modificados farão parte do próximo pacote de entrega (Staging Area).
2. git commit: Empacota e registra essas alterações no histórico local com uma mensagem explicativa.
3. git push: Envia os pacotes salvos da máquina virtual para o servidor remoto do GitHub.

1.5.1 Mão na Massa: Editando o README.md

Vamos praticar esse ciclo atualizando o arquivo README.md com os dados oficiais da TED System.

1. Na barra lateral esquerda do Codespaces (Explorador de Arquivos), clique em README.md para abri-lo no editor.
2. Apague o conteúdo original e adicione o seguinte texto:

README.md

# TED System

> Tecnologia que evolui com o seu negócio.

## Sobre a Empresa
Desenvolver soluções de software personalizadas, seguras e escaláveis que simplifiquem processos, aumentem a produtividade e impulsionem o crescimento dos nossos clientes.

## Localização
- **Endereço:** Rua Coronel Simplício, 250, Sala 12
- **Local:** Centro, Piripiri, PI - CEP 64260-000

## Equipe
- **Wanderson de Vasconcelos** — CEO e Engenheiro de Software
- **Sheldon Cooper** — Especialista Full Stack
- **Amy Farrah Fowler** — Especialista em Bancos de Dados

3. Salve o arquivo pressionando Ctrl + S (ou Cmd + S no Mac).

1.5.2 Verificando o Estado com git status

Volte ao terminal integrado e execute:

git status

O comando git status mostra a situação atual do seu projeto, informando quais arquivos foram alterados e ainda não foram salvos no histórico (documentação oficial do Git). O Git informará que o arquivo README.md foi modificado (modified: README.md), mas ainda não foi preparado para envio.

1.5.3 Preparando os arquivos: git add .

Para adicionar todos os arquivos modificados na área de preparação (staging), execute:

git add .

O comando git add prepara o conteúdo do arquivo para o próximo salvamento (documentação oficial do Git). O ponto (.) representa o diretório atual e todos os arquivos alterados dentro dele. Se você rodar git status novamente agora, verá que o nome do arquivo mudou para verde: ele está pronto para ser confirmado.

1.5.4 Verificando a Identidade do Git

Antes de fazermos o nosso primeiro salvamento oficial no histórico (o commit), o Git precisa saber quem está fazendo a alteração. Em um computador pessoal, você precisaria configurar seu nome e e-mail manualmente. No entanto, o GitHub Codespaces já configura a sua identidade automaticamente.

Vamos verificar se a sua identidade está correta executando:

git config user.name
git config user.email

Seu Nome
12345678+seu-usuario@users.noreply.github.com

Note que o e-mail retornado (como o @users.noreply.github.com do exemplo) é um e-mail privado gerado automaticamente pelo GitHub. Isso protege o seu e-mail pessoal contra spam, ao mesmo tempo em que garante que as suas contribuições fiquem vinculadas corretamente ao seu perfil.

1.5.5 Criando o ponto de restauração: git commit

Agora, registramos a alteração com uma mensagem clara sobre o que foi feito:

git commit -m "Adiciona informações da TED System ao README"

O comando git commit grava a alteração no histórico do repositório local (documentação oficial do Git). A flag -m indica a mensagem do commit. Use sempre mensagens descritivas para que você e sua equipe entendam o histórico do projeto no futuro.

1.5.6 Enviando para o GitHub: git push

Por fim, enviamos o commit registrado localmente no contêiner para o repositório remoto no GitHub:

git push

O comando git push envia o seu histórico local salvo para o repositório no GitHub na nuvem (documentação oficial do Git). Pronto! Acesse a aba do seu repositório no GitHub (ou atualize a página) e você verá o arquivo README.md devidamente atualizado com as informações da TED System.

AvisoAtenção: Nunca feche o navegador sem dar git push!

O GitHub Codespaces é uma máquina virtual que entra em modo de suspensão (sleep) após períodos de inatividade e pode ser recriada. Se você apenas alterar os arquivos sem fazer o commit e o git push, corre o risco de perder seu progresso caso o ambiente expire.

Crie o hábito profissional: terminou uma etapa de trabalho? Faça git add ., git commit -m "..." e git push imediatamente!

1.6 Resumo e Próximos Passos

Parabéns! Você acabou de configurar um ambiente de desenvolvimento profissional baseado em nuvem.

Neste capítulo, você aprendeu a:

• Criar um repositório público no GitHub para hospedar seu código;
• Iniciar o GitHub Codespaces e programar via navegador sem qualquer instalação local;
• Verificar a versão ativa do interpretador Node.js no ambiente;
• Utilizar o terminal Linux integrado e o comando pwd para localizar diretórios;
• Executar os passos essenciais do Git: git add . → git commit -m "..." → git push.

No próximo capítulo, começaremos a trabalhar com o Astro. Vamos inicializar a estrutura do nosso projeto e conhecer os principais conceitos dessa ferramenta. Até lá!