Capítulo 01 — Caixa de ferramentas do dev web

🎯 Objetivos de aprendizagem¶

Ao final deste capítulo você será capaz de:

• Navegar, criar pastas e ler arquivos pelo terminal (pwd, ls, cd, mkdir, cat, code .) em Linux, macOS e Windows, sabendo qual shell está usando.
• Configurar o VS Code com as extensões recomendadas nesta trilha e um settings.json que formata o código ao salvar.
• Usar as abas Elements, Console, Network e Lighthouse do DevTools, e o modo de dispositivo, para inspecionar qualquer página da Web.
• Instalar o Node.js LTS por um gerenciador de versões (nvm no Linux/macOS, nvm-windows no Windows) e explicar por que isso é melhor do que o instalador comum.
• Ler um package.json e usar npm init, npm install, npm run e npx com segurança.
• Conferir versões (node -v, npm -v, git --version, npm ls) e diagnosticar um ambiente quebrado.
• Padronizar indentação, codificação e fim de linha em qualquer editor com um .editorconfig.

📋 Pré-requisitos¶

• [ ] Um computador em que você possa instalar programas (Linux, macOS ou Windows 10/11).
• [ ] Cerca de 2 GB livres em disco e acesso à internet.
• [ ] Uma conta de e-mail que você acesse — vai servir para o GitHub no Capítulo 02.

Este é o primeiro capítulo da trilha Deploy & Ferramentas; não há capítulo anterior para retomar. Se você está no Nível 1, faça-o antes ou junto com a Aula 02 — tudo aqui usa só HTML, CSS e o navegador. Se está no Nível 2 ou 3, use-o como revisão do ambiente: é comum descobrir que o node -v da máquina é de dois anos atrás. Hoje você monta a bancada de trabalho; no Capítulo 02, aprende a guardar o histórico dela com Git.

🗺️ Roteiro¶

1. Por que uma caixa de ferramentas¶

Um site é só um conjunto de arquivos de texto. Dá para escrever HTML no Bloco de Notas e abrir com dois cliques — e nas primeiras aulas do Nível 1 isso basta. O problema aparece na terceira semana: você tem cinco páginas, uma pasta de imagens, um CSS que não recarrega, um colega que quer ver o site na máquina dele e, no fim do semestre, precisa publicar tudo em um endereço público.

Cada ferramenta deste capítulo resolve uma dor específica:

Você não precisa dominar tudo hoje. Precisa instalar tudo hoje, entender para que serve cada peça e saber onde conferir se está funcionando. É o que a maioria dos "não roda na minha máquina" do semestre tem em comum: uma peça faltando na bancada.

🧠 Você sabia? O bash, terminal padrão da maioria das distribuições Linux, é mais velho que a Web. Foi escrito por Brian Fox para o projeto GNU, e o nome é um trocadilho: Bourne Again SHell, em homenagem ao sh de Stephen Bourne, que ele substituiu. Os comandos ls, cd e cat que você vai usar hoje são os mesmos que um programador usava em um terminal de texto verde décadas antes de existir navegador.

2. O terminal¶

2.1 Qual terminal usar¶

O terminal é um programa que recebe comandos digitados e mostra o resultado em texto. O que interpreta os comandos se chama shell, e há vários. Para que os comandos deste material funcionem iguais em todas as máquinas, a recomendação é:

No Windows existe também o PowerShell, que aceita ls, cd, pwd, cat e mkdir como apelidos de comandos próprios — mas sem as opções do Linux (ls -la dá erro lá) e sem touch. Para não ter dois conjuntos de comandos na cabeça, use o Git Bash ao longo de toda esta trilha. Você instala o Git for Windows no passo a passo deste capítulo e ganha os dois de uma vez: o git e um shell compatível com Linux.

💡 Dica Quem usa Windows e quer um Linux "de verdade" dentro do Windows pode instalar o WSL (wsl --install em um PowerShell como administrador). Não é obrigatório para nada do WebLab; o Git Bash resolve tudo do que precisamos.

Para descobrir qual shell está rodando:

echo $SHELL

Saída típica: /bin/bash (Linux, Git Bash) ou /bin/zsh (macOS).

2.2 Onde estou, o que tem aqui, para onde vou¶

Todo terminal está sempre "dentro" de uma pasta, chamada diretório de trabalho. Três comandos resolvem 80 % da navegação:

pwd          # print working directory: mostra em que pasta você está
ls           # lista o conteúdo da pasta atual
cd Documentos  # change directory: entra na pasta Documentos

Variações de ls que você vai usar todo dia:

ls -l        # formato longo: permissões, dono, tamanho, data de cada item
ls -a        # inclui arquivos ocultos (os que começam com ponto, como .gitignore)
ls -la       # os dois juntos — o mais usado
ls css       # lista o conteúdo de uma subpasta sem entrar nela

Variações de cd:

cd ..        # sobe um nível (para a pasta "pai")
cd ../..     # sobe dois níveis
cd ~         # vai para a sua pasta pessoal (home)
cd           # o mesmo que cd ~
cd -         # volta para a pasta em que você estava antes
cd /         # vai para a raiz do sistema de arquivos

🔬 Investigue Abra o terminal e rode pwd, depois ls -la. Quantos itens começam com ponto? Eles não aparecem no gerenciador de arquivos comum — são configurações de programas (.bashrc, .config, .ssh). Agora rode cd / e ls: você está vendo a raiz do sistema. Volte com cd -. Em nenhum momento você "quebrou" nada: navegar é só olhar.

2.3 Criando e lendo arquivos¶

mkdir projetos               # cria a pasta projetos
mkdir -p projetos/site/css   # cria a cadeia inteira de pastas de uma vez (-p = parents)
touch index.html             # cria um arquivo vazio (ou atualiza a data de um existente)
cat index.html               # mostra o conteúdo de um arquivo de texto na tela
cp index.html contato.html   # copia
mv contato.html paginas/     # move (ou renomeia, se o destino for um nome de arquivo)
rm rascunho.html             # apaga um arquivo — sem lixeira, sem desfazer
rm -r pasta-velha            # apaga uma pasta e tudo dentro dela — cuidado dobrado
clear                        # limpa a tela (ou Ctrl+L)

E o comando que você mais vai digitar neste semestre:

code .

Abre o VS Code com a pasta atual como projeto. O ponto significa "aqui". Abrir a pasta (e não um arquivo solto) é o que faz o Live Server, o Git e as extensões entenderem onde o projeto começa.

⚠️ Atenção rm não pergunta e não tem lixeira. rm -rf com o caminho errado apaga pastas inteiras em silêncio. Antes de qualquer rm -r, rode ls no alvo para ter certeza do que vai sumir. E nunca copie um comando com rm -rf da internet sem entender cada parte dele.

2.4 Caminhos absolutos e relativos¶

Um caminho absoluto começa na raiz e não depende de onde você está: /home/ana/projetos/site/index.html (Linux), /Users/ana/projetos/site/index.html (macOS), C:\Users\ana\projetos\site\index.html (Windows — no Git Bash aparece como /c/Users/ana/…).

Um caminho relativo parte do diretório de trabalho: se você está em projetos/site, então css/estilo.css é o arquivo dentro da subpasta css, e ../outro-site é a pasta irmã.

Essa distinção volta com força no Capítulo 03: um href="/css/estilo.css" (absoluto, começa com barra) funciona no seu computador e quebra quando o site é publicado em um subcaminho como usuario.github.io/site-evento/. Guarde a ideia: barra no início = "a partir da raiz".

2.5 Truques que economizam horas¶

• Tab completa nomes de arquivos e pastas. Digite cd Doc e aperte Tab: vira cd Documentos/. Dois Tab mostram as opções quando há mais de uma.
• ↑ e ↓ percorrem o histórico de comandos. history lista tudo.
• Ctrl+C interrompe o programa em execução (é assim que você para um servidor de desenvolvimento).
• Ctrl+R busca no histórico: digite parte de um comando antigo e ele aparece.
• Arraste uma pasta do gerenciador de arquivos para a janela do terminal: o caminho absoluto dela é colado.
• Nomes com espaço precisam de aspas ou barra invertida: cd "Meus Projetos" ou cd Meus\ Projetos. Melhor ainda: não use espaços nem acentos em nomes de pastas de projeto. site-evento, não Site do Evento.

3. VS Code¶

3.1 Instalação e o comando code¶

Baixe em https://code.visualstudio.com e instale. Três detalhes por sistema:

• Windows: no instalador, marque "Add to PATH" e as opções "Open with Code" no menu de contexto. Sem o PATH, code . não funciona no terminal.
• macOS: abra o VS Code, aperte Cmd+Shift+P e execute Shell Command: Install 'code' command in PATH. Só assim code . funciona no Terminal.
• Linux: o pacote .deb/.rpm já registra o comando. Em distribuições com Snap, sudo snap install code --classic.

Teste:

code --version

A saída tem três linhas: a versão, um hash do build e a arquitetura (x64 ou arm64).

3.2 Extensões recomendadas¶

Extensões são instaladas pela aba Extensions (Ctrl+Shift+X) ou pelo terminal, o que é mais rápido e reproduzível. O identificador de cada uma é editor.nome:

Instalação de todas de uma vez:

code --install-extension ritwickdey.LiveServer
code --install-extension esbenp.prettier-vscode
code --install-extension dbaeumer.vscode-eslint
code --install-extension Vue.volar
code --install-extension humao.rest-client
code --install-extension eamodio.gitlens
code --install-extension EditorConfig.EditorConfig

Para conferir o que está instalado:

code --list-extensions

💡 Dica Prefere o VS Code em português? Instale MS-CEINTL.vscode-language-pack-pt-BR. Este material usa os nomes em inglês dos menus e abas (Settings, Extensions, Elements) porque é assim que aparecem na documentação oficial e nas respostas do Stack Overflow — vale a pena se acostumar com eles.

3.3 settings.json¶

As configurações do VS Code vivem em um arquivo JSON. Abra-o com Ctrl+Shift+P → Preferences: Open User Settings (JSON). Cole (ou mescle) isto:

settings.json (configurações do usuário)

{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "editor.tabSize": 2,
  "editor.insertSpaces": true,
  "editor.wordWrap": "on",
  "editor.linkedEditing": true,
  "editor.bracketPairColorization.enabled": true,
  "files.eol": "\n",
  "files.insertFinalNewline": true,
  "files.trimTrailingWhitespace": true,
  "emmet.variables": { "lang": "pt-BR" },
  "liveServer.settings.donotShowInfoMsg": true,
  "terminal.integrated.defaultProfile.windows": "Git Bash",
  "[markdown]": { "files.trimTrailingWhitespace": false }
}

O que cada linha faz:

• editor.formatOnSave + editor.defaultFormatter: ao salvar, o Prettier reorganiza indentação, aspas e quebras de linha. Você para de gastar atenção com estética e passa a gastar com lógica.
• editor.tabSize: 2 + insertSpaces: dois espaços por nível, o padrão do ecossistema JavaScript/Vue.
• editor.linkedEditing: renomear a tag de abertura de um elemento HTML renomeia a de fechamento junto.
• files.eol: "\n": fim de linha no padrão Unix. Evita o aviso LF will be replaced by CRLF do Git no Windows.
• emmet.variables.lang: o atalho ! do Emmet passa a gerar <html lang="pt-BR"> em vez de en.
• terminal.integrated.defaultProfile.windows: o terminal integrado do VS Code no Windows abre o Git Bash, não o PowerShell.

Há também configurações por projeto, em .vscode/settings.json dentro da pasta do projeto. Elas valem só ali e podem ser versionadas — útil para uma equipe usar o mesmo formatador.

3.4 Prettier: .prettierrc¶

O Prettier tem opiniões fortes e poucas opções. As que mudamos no WebLab ficam em um arquivo na raiz do projeto, e o estilo bate com o código que você vê nas aulas (sem ponto e vírgula, aspas simples):

.prettierrc

{
  "semi": false,
  "singleQuote": true,
  "printWidth": 100,
  "trailingComma": "es5"
}

Sem esse arquivo, o Prettier usa os padrões dele (com ponto e vírgula e aspas duplas). Nenhum dos dois estilos é "errado" — o que importa é o projeto inteiro seguir um só.

3.5 .editorconfig¶

O .prettierrc fala com o Prettier; o .editorconfig fala com qualquer editor (VS Code, Sublime, IntelliJ, Vim). Ele define o básico da forma do arquivo — indentação, codificação, fim de linha — e é lido pela extensão EditorConfig. Coloque na raiz de todo projeto:

.editorconfig

# Configuração lida por qualquer editor com suporte a EditorConfig
root = true

[*]
charset = utf-8
end_of_line = lf
insert_final_newline = true
trim_trailing_whitespace = true
indent_style = space
indent_size = 2

[*.md]
trim_trailing_whitespace = false

root = true diz "pare de procurar .editorconfig nas pastas acima". A seção [*] vale para todo arquivo; a [*.md] abre uma exceção para Markdown, em que dois espaços no fim da linha significam quebra de linha.

3.6 Atalhos essenciais¶

No macOS, troque Ctrl por Cmd e Alt por Option.

3.7 Emmet: HTML em uma linha¶

O VS Code traz o Emmet embutido: você digita uma abreviação e aperta Tab. Em um arquivo .html:

• ! → esqueleto completo (<!DOCTYPE html>, <html lang="pt-BR">, <meta viewport>, <title>).
• ul>li*3 → uma lista com três itens.
• .card>h2+p → uma div.card com um h2 e um p dentro.
• a[href="contato.html"]{Contato} → um link com atributo e texto.
• table>tr*3>td*2 → uma tabela 3×2.

Vale a pena passar dez minutos no cheat sheet oficial (https://docs.emmet.io/cheat-sheet/); as páginas do site do evento saem em metade do tempo.

4. DevTools: o raio-X do navegador¶

Todo navegador moderno traz ferramentas de desenvolvedor. Abra com F12, Ctrl+Shift+I ou botão direito → Inspecionar (no macOS, Cmd+Option+I). Os exemplos aqui são do Chrome; o Firefox tem as mesmas abas com nomes quase iguais.

4.1 Elements — o HTML como o navegador entendeu¶

A aba Elements mostra a árvore DOM: não o seu arquivo, mas o que o navegador construiu a partir dele (com tags que ele fechou por você, com o que o JavaScript inseriu). Ao clicar em um elemento:

• O painel Styles lista cada regra CSS que atinge o elemento, em ordem de prioridade, com as sobrescritas riscadas. É onde você descobre por que "meu CSS não aplica": outra regra mais específica venceu, ou o seletor não bate.
• Você pode editar valores ao vivo (clique em 16px e digite 24px) para experimentar sem tocar no arquivo. Nada disso é salvo — é rascunho.
• O painel Computed mostra o valor final de cada propriedade e o diagrama de caixa (margin, border, padding, conteúdo).
• A lupa no canto superior esquerdo (Ctrl+Shift+C) seleciona um elemento clicando na página.

4.2 Console — o que o JavaScript tem a dizer¶

A aba Console mostra mensagens de console.log, avisos e erros em vermelho com o arquivo e a linha (script.js:12). Também é um interpretador: digite document.title e aperte Enter; digite 2 + 2; digite document.querySelectorAll('a').length para contar os links da página. Nas aulas de JavaScript do Nível 1 você vai passar mais tempo aqui do que no editor.

4.3 Network — cada arquivo que a página pediu¶

A aba Network grava tudo o que o navegador baixou: HTML, CSS, imagens, fontes, scripts, chamadas a APIs. Para cada requisição: Status (200 ok, 404 não encontrado, 304 não mudou), Type, Size e Time. A linha do tempo à direita (o waterfall) mostra o que esperou por quem.

Três hábitos:

1. Abra o DevTools antes de recarregar (F5), senão a aba fica vazia.
2. Marque Disable cache enquanto desenvolve, para sempre ver a versão nova do CSS.
3. Use o seletor de velocidade (No throttling → Slow 4G) para sentir o site como quem está no 4G ruim do interior.

Na barra de baixo, o resumo: número de requisições, total transferido, tempo até DOMContentLoaded e até Load.

4.4 Device toolbar — o site no celular¶

Ctrl+Shift+M liga o modo de dispositivo: a página é renderizada nas dimensões de um celular ou tablet, com toque simulado. Escolha um aparelho na lista ou digite largura e altura. É a ferramenta central da aula de telas responsivas do Nível 1 — mas lembre que é uma simulação: fontes, desempenho e o teclado virtual só se veem em um celular de verdade.

4.5 Lighthouse — a nota do seu site¶

A aba Lighthouse roda uma auditoria automática e dá notas de 0 a 100 em quatro categorias: Performance, Accessibility, Best Practices e SEO. Escolha Mobile, clique em Analyze page load e espere um minuto. Cada item reprovado vem com explicação e link. É o critério objetivo de "site bom" usado nos checkpoints das trilhas: ≥ 90 em Performance e Accessibility.

4.6 Sources e Application — para depois¶

Sources permite colocar pontos de parada (breakpoints) no JavaScript e executar linha a linha — você vai usar nas aulas de funções e eventos. Application mostra localStorage, cookies e service workers — aparece no Nível 3, quando o UniEventos guarda inscrições no navegador.

🔬 Investigue Abra https://weblab.aprendabit.com com a aba Network aberta e Disable cache marcado. Recarregue. Anote: quantas requisições? Qual o maior arquivo (clique no cabeçalho Size para ordenar)? Quanto tempo até DOMContentLoaded? Agora mude para Slow 4G e recarregue de novo. O que mais demorou? Esse é o tipo de medição que você vai repetir no seu próprio site publicado, no Capítulo 03.

5. Node.js e npm¶

5.1 Por que um dev front-end precisa de Node¶

O Node.js roda JavaScript fora do navegador. Você só vai escrever servidores com ele no Nível 2 — mas precisa dele desde já porque as ferramentas do ofício são escritas em JavaScript: o Prettier que formata seu CSS, o ESLint que aponta erros, o Vite que empacota o Vue, o serve que sobe um servidor local. Todas são instaladas e executadas pelo npm, o gerenciador de pacotes que vem junto com o Node.

Pense no npm como uma loja de aplicativos para código: qualquer pessoa publica um pacote (uma pasta com JavaScript e um package.json), e qualquer projeto instala esse pacote com um comando. O registro público tem milhões de pacotes, do minúsculo ao gigantesco.

🧠 Você sabia? Um pacote chamado left-pad, com 11 linhas que só adicionavam espaços à esquerda de um texto, era dependência indireta de milhares de projetos. Quando o autor o removeu do npm em uma disputa, builds do mundo inteiro quebraram na mesma tarde — e o npm mudou as regras para impedir a remoção de pacotes publicados. É a lição de que todo npm install é um ato de confiança em desconhecidos; o package-lock.json, que você vai ver adiante, existe para tornar essa confiança pelo menos reproduzível.

5.2 LTS e o gerenciador de versões¶

O Node tem duas linhas: Current (versões ímpares, novidades primeiro, suporte curto) e LTS (Long Term Support — versões pares, recebem correções por anos). Use sempre a LTS: hoje, a linha 22 (a 24 também é LTS e funciona). O create-vue do Nível 3 exige ^22.18.0 || >=24.12.0, o que é mais um motivo para não ficar com um Node velho.

Há dois jeitos de instalar. O instalador de https://nodejs.org funciona, mas deixa uma versão única e fixa, e no Linux/macOS costuma exigir sudo para instalar pacotes globais. O jeito recomendado é um gerenciador de versões, que instala o Node na sua pasta pessoal (sem sudo) e permite ter várias versões lado a lado — o projeto antigo de um freela em Node 18, o projeto novo em Node 22.

Linux e macOS — nvm. Copie o comando de instalação da página oficial (https://github.com/nvm-sh/nvm#installing-and-updating); ele tem este formato, com a versão atual do nvm no meio da URL:

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash

Feche e abra o terminal (o instalador acrescenta linhas ao ~/.bashrc ou ~/.zshrc, que só são lidas em um terminal novo). Depois:

nvm install --lts          # baixa e instala a LTS mais recente
nvm use --lts              # ativa nesta sessão
nvm alias default 'lts/*'  # torna a LTS o padrão de todo terminal novo
nvm ls                     # lista as versões instaladas (a ativa tem ->)
node -v                    # v22.x.x (ou v24.x.x)
npm -v                     # 10.x.x ou 11.x.x

Para uma versão específica: nvm install 22, nvm use 22.

Windows — nvm-windows. É um projeto diferente, com comandos parecidos. Baixe o nvm-setup.exe em https://github.com/coreybutler/nvm-windows/releases, instale e abra um Git Bash novo:

nvm install lts    # instala a LTS mais recente
nvm list           # mostra o número exato da versão instalada
nvm use lts        # ativa (pode pedir um terminal como administrador)
node -v
npm -v

Se preferir não usar gerenciador no Windows, o instalador oficial também serve: winget install OpenJS.NodeJS.LTS em um PowerShell, ou o .msi do site. Você perde a troca de versões, mas ganha simplicidade.

5.3 npm: os quatro comandos¶

Entre em uma pasta de projeto e:

npm init -y

Cria um package.json com valores padrão (o -y aceita todas as perguntas). Em seguida:

npm install prettier --save-dev   # instala um pacote como dependência de desenvolvimento
npm install                       # instala tudo que o package.json lista (ao clonar um projeto)
npm run formatar                  # executa o script "formatar" definido em package.json
npx prettier --check .            # executa um pacote sem instalar globalmente

• npm install <pacote> (ou npm i) baixa o pacote para node_modules/ e o registra em dependencies. Com -D (ou --save-dev), registra em devDependencies — coisas que só existem enquanto você desenvolve (formatador, empacotador, ferramentas de teste), e não no site final.
• npm install sem argumentos lê package.json e package-lock.json e recria node_modules/ inteira. É o primeiro comando que você roda ao baixar qualquer projeto Node.
• npm run <nome> executa um comando definido em scripts. npm run sem nome lista os scripts disponíveis.
• npx <comando> procura o executável em node_modules/.bin do projeto; se não existir, baixa uma cópia temporária e pergunta se pode executar. É assim que você usa npx create-vue@latest sem instalar nada antes.

5.4 package.json explicado¶

Depois de npm init -y, npm install -D prettier serve e a edição dos scripts, o arquivo de um projeto de teste fica assim (a ordem dos campos e um ou outro campo extra variam com a versão do npm):

package.json

{
  "name": "ola-weblab",
  "version": "1.0.0",
  "description": "Projeto de teste do ambiente WebLab",
  "scripts": {
    "dev": "serve . -l 3000",
    "formatar": "prettier --write .",
    "verificar": "prettier --check ."
  },
  "keywords": [],
  "author": "Seu Nome",
  "license": "MIT",
  "devDependencies": {
    "prettier": "^3.6.2",
    "serve": "^14.2.4"
  }
}

Campo a campo:

O ^ antes da versão é semver (versionamento semântico): ^3.6.2 aceita qualquer 3.x.y a partir de 3.6.2, mas não 4.0.0. O primeiro número muda quando há quebra de compatibilidade; o segundo, quando há funcionalidade nova; o terceiro, quando há correção.

🔎 Por baixo do capô Ao rodar npm install, o npm lê package.json, resolve a árvore de dependências (cada pacote depende de outros, que dependem de outros), baixa tudo do registro para node_modules/ e grava em package-lock.json a versão exata de cada pacote instalado. Os executáveis dos pacotes ganham um atalho em node_modules/.bin/ — é por isso que serve funciona dentro de scripts sem caminho: o npm coloca essa pasta no PATH enquanto roda um script. E é por isso que npx serve acha o serve do projeto antes de pensar em baixar qualquer coisa.

5.5 node_modules e package-lock.json¶

Duas regras que evitam metade dos problemas de Git do semestre:

1. node_modules/ nunca vai para o Git nem para o .zip. É regenerável com npm install, pesa dezenas ou centenas de megabytes e tem milhares de arquivos.
2. package-lock.json sempre vai para o Git. Ele garante que qualquer pessoa — um colega ou o servidor — instale exatamente as mesmas versões que você testou.

6. Gerenciando versões¶

Quando algo "não funciona", a primeira pergunta é: qual versão? Comandos de diagnóstico:

node -v              # versão do Node ativa
npm -v               # versão do npm
git --version        # versão do Git
nvm current          # qual Node o nvm ativou nesta sessão (Linux/macOS)
which node           # de onde o executável node está vindo
npm ls --depth=0     # pacotes instalados no projeto, sem as dependências das dependências
npm outdated         # o que tem versão nova disponível
npm view vite version  # última versão publicada de um pacote

Para fixar a versão do Node por projeto, crie um .nvmrc na raiz com o número da linha:

.nvmrc

22

Quem entrar na pasta e rodar nvm use recebe a versão certa sem pensar. Muitos projetos também declaram o mesmo em package.json, no campo engines:

{
  "engines": {
    "node": ">=22.18.0"
  }
}

⚠️ Atenção Se node -v mostra uma versão diferente da que você acabou de instalar com o nvm, há dois Nodes na máquina: um do instalador antigo, outro do nvm. which -a node lista todos. Desinstale o antigo (ou deixe nvm alias default decidir) para não passar o semestre com um ambiente que muda a cada terminal.

🚀 Passo a passo — Ambiente pronto e um projeto de teste no Live Server¶

Ao fim destes passos, sua máquina responde a node -v, npm -v e git --version, o VS Code tem as extensões recomendadas, e um projeto mínimo abre no navegador pelo Live Server e recarrega sozinho ao salvar. Faça na ordem; cada passo tem um jeito de conferir.

Passo 1 — Git (e o Git Bash, no Windows)¶

• Windows: baixe e instale o Git for Windows em https://git-scm.com/download/win (ou winget install --id Git.Git -e --source winget no PowerShell). Aceite os padrões; ele instala o Git Bash.
• macOS: no Terminal, git --version. Se não estiver instalado, o sistema oferece as Command Line Tools; aceite. Alternativa: brew install git.
• Linux (Ubuntu/Debian): sudo apt update && sudo apt install git.

Conferir (em um terminal novo):

git --version

Esperado: git version 2.x.y.

Passo 2 — VS Code e o comando code¶

Instale conforme a §3.1 e, em um terminal novo:

code --version

Esperado: três linhas, começando pela versão. No Windows, use o Git Bash; no macOS, só funciona depois do Shell Command: Install 'code' command in PATH.

Passo 3 — extensões¶

code --install-extension ritwickdey.LiveServer
code --install-extension esbenp.prettier-vscode
code --install-extension dbaeumer.vscode-eslint
code --install-extension Vue.volar
code --install-extension humao.rest-client
code --install-extension eamodio.gitlens
code --install-extension EditorConfig.EditorConfig
code --list-extensions

Esperado: a última linha lista as sete extensões.

Passo 4 — settings.json¶

No VS Code, Ctrl+Shift+P → Preferences: Open User Settings (JSON) → cole o conteúdo da §3.3 → salve. Se o arquivo já tinha conteúdo, mescle dentro das mesmas chaves { }.

Passo 5 — Node.js LTS¶

Siga a §5.2 para o seu sistema. Conferir, em um terminal novo:

node -v
npm -v
npx -v

Esperado: v22.x.x (ou v24.x.x), 10.x.x (ou 11.x.x) e o mesmo número do npm.

Passo 6 — a pasta de projetos e o projeto de teste¶

Crie uma pasta para todos os projetos do WebLab e, dentro dela, o projeto de teste:

mkdir -p ~/weblab/ola-weblab
cd ~/weblab/ola-weblab
mkdir css js
touch index.html css/estilo.css js/script.js
ls -R

Esperado:

.:
css  index.html  js

./css:
estilo.css

./js:
script.js

Abra no VS Code:

code .

Passo 7 — os três arquivos¶

index.html (digite ! e Tab para o esqueleto, depois complete)

<!DOCTYPE html>
<html lang="pt-BR">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Olá, WebLab</title>
    <link rel="stylesheet" href="css/estilo.css" />
  </head>
  <body>
    <main>
      <h1>Ambiente pronto</h1>
      <p>Se esta página recarregou sozinha quando você salvou, o Live Server está funcionando.</p>
      <p id="relogio">Carregando o relógio pelo JavaScript…</p>
    </main>
    <script src="js/script.js"></script>
  </body>
</html>

css/estilo.css

/* Estilo mínimo só para provar que o CSS foi carregado */
body {
  font-family: system-ui, sans-serif;
  max-width: 40rem;
  margin: 2rem auto;
  padding: 0 1rem;
  background: #f5f5f0;
  color: #222;
}

h1 {
  color: #1b6b4a;
}

js/script.js

// Mostra a hora atual e prova que o JavaScript foi carregado
const relogio = document.querySelector('#relogio')

function atualizarRelogio() {
  const agora = new Date()
  relogio.textContent = `Agora são ${agora.toLocaleTimeString('pt-BR')}`
}

atualizarRelogio()
setInterval(atualizarRelogio, 1000)

console.log('Ambiente WebLab: JavaScript carregado com sucesso')

Passo 8 — Live Server¶

Com index.html aberto, clique em Go Live no canto inferior direito da janela (ou botão direito no arquivo → Open with Live Server). O navegador abre http://127.0.0.1:5500/index.html.

Mude o texto do <h1> e salve: a página recarrega sozinha. Abra o DevTools (F12) → Console: a mensagem Ambiente WebLab: JavaScript carregado com sucesso está lá. Aba Network, recarregue: quatro requisições (index.html, estilo.css, script.js e um favicon.ico com 404 — normal, ainda não há favicon; o Capítulo 03 resolve).

Passo 9 — npm init e os arquivos de padronização¶

No terminal integrado do VS Code (Ctrl+</kbd>), dentro deola-weblab`:

npm init -y
npm install -D prettier serve

Crie .prettierrc e .editorconfig com o conteúdo das §3.4 e §3.5, e acrescente os scripts ao package.json até ele ficar como na §5.4. Depois:

npm run formatar
npm run dev

Esperado: o Prettier lista os arquivos formatados; o serve sobe em http://localhost:3000 (é um segundo servidor local, sem recarga automática — serve para conferir que npm run funciona). Pare com Ctrl+C.

Como conferir¶

🧪 Laboratório¶

Nível A — Fixação¶

A1. Você está em ~/weblab/site-evento/css e roda cd .. e depois pwd. O que aparece? E se em seguida rodar cd ~ e pwd?

A2. Qual a diferença entre npm install prettier e npm install -D prettier? Em que campo do package.json cada um registra o pacote, e qual dos dois é o certo para um formatador?

A3. Preveja o que acontece ao rodar npx serve . em uma pasta que não tem o serve instalado nem localmente nem globalmente. O comando falha?

A4. Em uma pasta vazia, mkdir -p projetos/site/css cria quantas pastas? O que muda se projetos já existir? E o que acontece com mkdir projetos/site/css (sem -p) na pasta vazia?

A5. Para cada situação, diga qual aba do DevTools responde: (a) "por que o color: red não aplicou neste parágrafo?"; (b) "qual arquivo voltou com 404?"; (c) "o que meu console.log imprimiu?"; (d) "como o site fica em uma tela de 375 px?"; (e) "qual a nota de acessibilidade da página?".

A6. node -v e nvm current podem mostrar valores diferentes? Descreva uma situação em que isso acontece e como corrigir.

Nível B — Aplicação¶

B1. Estrutura em um comando. Crie, com um único mkdir e um único touch, a estrutura do site do evento: site-evento/index.html, programacao.html, inscricao.html, palestrantes.html, contato.html, css/estilo.css, js/script.js e a pasta img/ vazia. Mostre o resultado com ls -R.

Resultado esperado:

site-evento:
contato.html  css  img  index.html  inscricao.html  js  palestrantes.html  programacao.html

site-evento/css:
estilo.css

site-evento/img:

site-evento/js:
script.js

B2. Formatação automática. Crie js/bagunca.js com exatamente este conteúdo, salve e observe o que o Prettier faz:

const   produtos=[{nome:"Café",preco:5},{nome:"Pão de queijo",
preco:4}]
function total( lista ){let soma=0;for(const p of lista){soma+=p.preco};return soma}
console.log( total(produtos) );

Resultado esperado: ao salvar, o arquivo fica com dois espaços de indentação, aspas simples, sem ponto e vírgula, um item por linha no array e o for em várias linhas — sem você tocar em nada.

B3. Caçador de requisições. Com a aba Network aberta e Disable cache marcado, carregue a página inicial de três sites: https://weblab.aprendabit.com, o portal da sua universidade ou escola e um site de notícias à sua escolha. Para cada um, registre: número de requisições, total transferido, maior arquivo (nome e tamanho) e tempo até DOMContentLoaded. Repita com Slow 4G.

Resultado esperado: uma tabela com três linhas e as medições nas duas velocidades, mais uma frase por site dizendo qual recurso mais atrasou o carregamento no 4G lento.

B4. Scripts próprios. No projeto ola-weblab, acrescente ao package.json um script abrir que executa code ., e um script limpar que apaga node_modules (rm -rf node_modules). Rode npm run limpar, confira com ls -a que a pasta sumiu, e depois npm install para recriá-la.

Resultado esperado: npm run lista cinco scripts; depois de npm install, npm ls --depth=0 volta a mostrar prettier e serve com as mesmas versões de antes (é o package-lock.json garantindo isso).

Nível C — Desafio¶

C1. Gerador de projeto. Escreva um script novo-projeto.sh que receba um nome (bash novo-projeto.sh cardapio) e: recuse se a pasta já existir; crie a pasta com index.html (esqueleto completo com lang="pt-BR", viewport e título igual ao nome), css/estilo.css, js/script.js, .editorconfig e .prettierrc; e termine abrindo o VS Code na pasta. Torne-o executável e use-o para criar a pasta do seu projeto autoral.

🏆 Desafios¶

🐛 Erros comuns¶

🏠 Para praticar depois da aula (1 h)¶

Monte o ambiente completo e crie a pasta do seu projeto autoral (o site com o tema que você escolheu na sua trilha):

1. Siga o passo a passo até o fim; corrija qualquer item da tabela "Como conferir" que não bata.
2. Crie a pasta do projeto autoral em ~/weblab/<nome-do-projeto> (sem espaços nem acentos) com index.html, css/estilo.css, js/script.js, .editorconfig e .prettierrc. O index.html deve ter lang="pt-BR", viewport, um <title> com o nome do projeto e um <h1>.
3. Abra com o Live Server e deixe um console.log com o nome do projeto no script.js.
4. Tire três capturas de tela: (a) o terminal com a saída de node -v, npm -v e git --version; (b) o terminal com code --list-extensions; (c) o navegador com o site no Live Server e o DevTools aberto na aba Console mostrando a sua mensagem.

Critério de pronto: as três capturas mostram versões LTS do Node, as sete extensões e a mensagem no Console; a pasta do projeto tem os cinco arquivos e não contém node_modules.

Guarde: um .zip da pasta do projeto (sem node_modules) e as três capturas em um único PDF, num lugar seguro. A partir do Capítulo 02, isso vira o link do repositório no GitHub.

✅ Está no ar quando…¶

Nada vai ao ar neste capítulo — a bancada é que fica pronta. Confira:

• [ ] node -v imprime v22.x.x ou v24.x.x; npm -v imprime 10.x.x ou superior; git --version imprime 2.x.y.
• [ ] code . abre o VS Code na pasta atual, a partir do terminal recomendado para o seu sistema.
• [ ] code --list-extensions lista Live Server, Prettier, ESLint, Vue - Official, REST Client, GitLens e EditorConfig.
• [ ] Salvar um arquivo mal indentado o reformata (Prettier + formatOnSave).
• [ ] O Live Server serve o index.html em 127.0.0.1:5500 e recarrega ao salvar.
• [ ] Você encontra um console.log na aba Console e um 404 na aba Network sem ajuda.
• [ ] A pasta do projeto autoral existe, com .editorconfig e .prettierrc na raiz e sem node_modules no que será entregue.
• [ ] Você sabe explicar, em uma frase, a diferença entre npm install, npm run e npx.

📚 Para aprofundar¶

• VS Code — documentação oficial (introdução, terminal integrado, atalhos): https://code.visualstudio.com/docs
• VS Code — referência de atalhos em PDF (Linux, macOS, Windows): https://code.visualstudio.com/docs/configure/keybindings
• Emmet — cheat sheet oficial: https://docs.emmet.io/cheat-sheet/
• Chrome DevTools — guia oficial em português (Elements, Console, Network, Lighthouse): https://developer.chrome.com/docs/devtools?hl=pt-br
• Node.js — trilha "Aprenda" em português (o que é Node, como instalar, npm): https://nodejs.org/pt/learn
• nvm — instalação e uso: https://github.com/nvm-sh/nvm#installing-and-updating
• nvm-windows — releases e instruções: https://github.com/coreybutler/nvm-windows
• npm — documentação de package.json e dos comandos: https://docs.npmjs.com/cli/v10/configuring-npm/package-json
• Prettier — opções de configuração: https://prettier.io/docs/options
• EditorConfig — especificação e exemplos: https://editorconfig.org
• Pro Git (capítulo 1, "Começando", para chegar preparado ao Capítulo 02): https://git-scm.com/book/pt-br/v2

No próximo capítulo, a bancada ganha memória: Git para guardar cada versão do projeto e GitHub para publicá-lo, colaborar e abrir o seu primeiro pull request.