Ferramentas: npm, Vite e qualidade
Pacotes, scripts, lockfile, servidor de desenvolvimento e build; e por que segredo nunca vai para o frontend.
Cerca de 12 min · Revisado em
Ao final, você vai conseguir
- Ler um package.json e rodar scripts
- Explicar o papel do lockfile
- Criar um projeto com Vite e gerar o build
- Separar variáveis públicas de segredos
Até aqui você criou arquivos à mão e abriu no navegador. Projetos de verdade têm dezenas de arquivos, bibliotecas de outras pessoas, TypeScript para converter e código para deixar leve antes de publicar. Ninguém faz isso manualmente. Nesta aula você conhece as ferramentas que automatizam esse trabalho, e entende o que cada uma faz por baixo, para nunca depender de mágica.
Por que existem ferramentas
Uma boa regra: automatize o que você já entende. Você já sabe ligar um script ao HTML e conferir um tipo. As ferramentas fazem isso mais rápido, sem esquecer nenhum passo, em todos os computadores do time.
- Node.js
- Um programa que roda JavaScript fora do navegador, direto no seu computador. É ele que executa as ferramentas desta aula. Você instala uma vez e esquece.
- npm
- Vem junto com o Node.js. É ao mesmo tempo um registro público com milhões de pacotes e o comando que baixa e organiza esses pacotes no seu projeto.
- Pacote
- Código pronto que alguém publicou para outras pessoas usarem: uma biblioteca de datas, um framework, uma ferramenta como o Vite.
Você vai criar um site simples. Ele vai rodar no navegador das pessoas. Por que você precisa do Node.js instalado no seu computador?
- Para rodar as ferramentas de desenvolvimento, como npm e Vite
- Porque o navegador precisa do Node.js para entender JavaScript
- Porque todo site precisa de um servidor Node.js para ser publicado
O package.json, a ficha do projeto
Todo projeto com npm tem um arquivo package.json na raiz. Ele diz o nome do projeto, quais comandos existem e de quais pacotes ele depende. É o primeiro arquivo que vale abrir num projeto desconhecido.
Um package.json típico de projeto com Vite e TypeScript.
{
"name": "catalogo-de-lanches",
"private": true,
"type": "module",
"scripts": {
"dev": "vite",
"build": "tsc --noEmit && vite build",
"lint": "eslint ."
},
"dependencies": {
"dayjs": "^1.11.13"
},
"devDependencies": {
"eslint": "^9.30.0",
"typescript": "^5.9.0",
"vite": "^7.1.0"
}
}- Nome: Identifica o projeto. Letras minúsculas e hífens, sem espaços nem acentos.
- Scripts: Atalhos para comandos.
npm run devexecutavite. Nobuild, o&&quer dizer “só continue se o anterior deu certo”: primeiro confere os tipos, depois gera o site. - dependencies: Pacotes que o seu código usa enquanto roda no navegador. Aqui, uma biblioteca para formatar datas na tela.
- devDependencies: Ferramentas usadas só para desenvolver e construir. Elas trabalham no seu computador e não vão para o navegador de quem visita.
Os comandos do dia a dia.
npm install dayjs # adiciona em dependencies
npm install -D eslint # -D adiciona em devDependencies
npm run dev # roda o script "dev"
npm run build # roda o script "build"Num projeto de catálogo com Vite, onde cada pacote costuma ficar?
dependencies · devDependencies
vite, que monta o projetodayjs, que formata datas mostradas na telatypescript, que confere os tiposreact, que desenha a interface no navegadoreslint, que procura problemas no códigoprettier, que formata o código
Com o script "build": "tsc --noEmit && vite build", o que acontece ao rodar npm run build num projeto com um erro de tipo?
- O
tscfalha e ovite buildnem começa - Os dois rodam e o site é gerado com um aviso
- O Vite corrige o erro de tipo automaticamente
node_modules e o lockfile
Ao rodar npm install, o npm baixa os pacotes para a pasta node_modules, e também os pacotes de que eles dependem. Um projeto pequeno facilmente traz centenas de pastas ali. Essa pasta nunca vai para o Git: ela é listada no .gitignore e qualquer pessoa a recria com um comando.
Junto, o npm cria o package-lock.json, o lockfile (arquivo de trava). Ele registra a versão exata de cada pacote instalado, inclusive os indiretos. Esse arquivo vai, sim, para o Git.
| Arquivo ou pasta | Vai para o Git? | Por quê |
|---|---|---|
package.json | Sim | Lista o que o projeto precisa e os scripts |
package-lock.json | Sim | Garante as mesmas versões em todo computador |
node_modules/ | Não | É enorme e recriado com npm install ou npm ci |
dist/ | Não | É gerado pelo build a partir do código |
.env | Não | Pode ter configurações locais e valores sensíveis |
O projeto não tem lockfile no Git. Ana instala em março, Bruno em junho, ambos com "vite": "^7.1.0". O código funciona para Ana e quebra para Bruno. Qual a explicação mais provável?
- O
^deixou Bruno receber uma versão mais nova, com outro comportamento - O computador do Bruno é mais lento
- O
package.jsondo Bruno está diferente - O npm sempre instala versões aleatórias
Qual a diferença entre npm install e npm ci?
npm install pode atualizar o lockfile se encontrar algo diferente. npm ci (de “integração contínua”) apaga o node_modules e instala exatamente o que está no lockfile, falhando se ele não combinar com o package.json. Use npm ci em servidores de build e quando quiser reproduzir o ambiente de alguém.
Vite: servidor de desenvolvimento e build
O Vite é uma ferramenta de build: ele pega o código que você escreve e entrega ao navegador do jeito certo. Ele tem dois modos de trabalho, um para quando você está programando e outro para quando vai publicar.
Crie o projeto
O comando faz algumas perguntas. Para começar, escolha Vanilla (sem framework) e a variante TypeScript.
npm create vite@latest catalogoEntre na pasta e instale
O
npm installlê opackage.jsone baixa tudo paranode_modules.cd catalogo npm installLigue o servidor de desenvolvimento
O terminal mostra um endereço como
http://localhost:5173. Abra no navegador. Para desligar,Ctrl+Cno terminal.npm run devEdite e salve
Mude um texto em
src/main.tse salve. A página atualiza sozinha em menos de um segundo, sem você recarregar.
Os dois modos do Vite: desenvolvimento e build
- src/ → Vite: salvou main.ts. Com
npm run devligado, o Vite vigia a pastasrc/. Você salvou um arquivo. - Vite → Vite: remove tipos do arquivo. O Vite converte só o arquivo que mudou: apaga os tipos do TypeScript e entrega JavaScript. Por isso é tão rápido.
- Vite → Navegador: atualização instantânea. O navegador troca só o módulo alterado, sem recarregar a página. Isso se chama hot reload (recarga a quente).
- src/ → Vite: npm run build. Hora de publicar. O build lê o projeto inteiro de uma vez.
- Vite → Vite: junta, otimiza, minifica. Junta os arquivos, remove o que não é usado e encurta o código (minifica), para o site baixar rápido no celular.
- Vite → dist/: index.html + assets/. O resultado vai para a pasta
dist/: HTML, CSS e JavaScript prontos. É essa pasta que você publica. - dist/ → Navegador: site publicado. Uma hospedagem entrega os arquivos de
dist/. Quem visita não precisa de Node, npm nem Vite.
O Vite também entende módulos: arquivos que compartilham código com export e import. Em vez de um arquivo gigante, cada arquivo cuida de uma coisa.
Um arquivo exporta uma função; outro importa e usa.
src/precos.ts
export function formatarPreco(valor: number): string {
return 'R$ ' + valor.toFixed(2).replace('.', ',');
}src/main.ts
import { formatarPreco } from './precos';
console.log(formatarPreco(8)); // R$ 8,00Complete para compartilhar a função somarCarrinho entre dois arquivos.
// src/carrinho.ts
____ function somarCarrinho(precos: number[]) {
return precos.reduce((total, preco) => total + preco, 0);
}
// src/main.ts
____ { somarCarrinho } ____ './carrinho';Coloque em ordem os comandos para começar um projeto do zero e gerar a versão de publicação.
npm create vite@latest catalogocd catalogonpm installnpm run devnpm run buildnpm run preview
Lint e formatação: revisores automáticos
Duas ferramentas revisam o seu código a cada salvamento, antes de qualquer pessoa. Cada uma cuida de um tipo de problema, e juntas com o TypeScript formam uma rede de proteção.
- ESLint (lint)
- Procura padrões perigosos ou suspeitos: variável criada e nunca usada,
==no lugar de===, código que nunca roda. O nome vem de “lint”, os fiapos que grudam na roupa. - Prettier (formatação)
- Cuida só da aparência: espaços, aspas, quebras de linha, indentação. Ele reescreve o arquivo no mesmo estilo para todo o time, e ninguém mais discute vírgula em revisão.
tsc --noEmit- O compilador do TypeScript conferindo os tipos sem gerar arquivos. Vale ter como script próprio, por exemplo
"typecheck".
Qual ferramenta aponta ou corrige cada problema?
ESLint · Prettier · TypeScript
- Uma variável declarada que nunca é usada
- Aspas simples e duplas misturadas no mesmo arquivo
- Passar um texto onde a função espera número
- Usar
==em vez de=== - Indentação bagunçada depois de colar um trecho
- Acessar
produto.prco, um campo que não existe
Variáveis públicas e segredos
Alguns valores mudam conforme o ambiente: o endereço da API de testes é diferente do de produção. Eles ficam num arquivo .env, como variáveis de ambiente, fora do código.
Arquivo .env na raiz do projeto. Só o que começa com VITE_ chega ao seu código.
VITE_API_URL=https://api.exemplo.com.br
VITE_CHAVE_MAPA=chave_publica_restrita_ao_dominio
SENHA_BANCO=nunca_deveria_estar_aquiLendo a variável no código do frontend.
const urlApi = import.meta.env.VITE_API_URL;
const resposta = await fetch(urlApi + '/produtos');Este valor pode ir para o frontend, ou é um segredo que só pode ficar no servidor?
Pode ir no frontend · Segredo: só no servidor
- O endereço público da API
- A senha do banco de dados
- A chave secreta do serviço de pagamento
- Uma chave de mapa feita para uso público e restrita ao seu domínio
- A chave da API de um serviço de IA cobrado por uso
- O ID da ferramenta de estatísticas de visitas
- Um token com permissão de administrador no GitHub
Fechamento
- O Node.js roda JavaScript no seu computador, e o npm instala pacotes e executa os scripts do
package.json. dependenciesvão para o navegador;devDependenciessão ferramentas, instaladas comnpm install -D.node_modulesnunca vai para o Git; o lockfile vai, enpm cireproduz exatamente as mesmas versões.- O Vite atualiza a página na hora com
npm run deve gera a pastadist/para publicar comnpm run build. - Toda variável
VITE_fica pública no build: segredos ficam só no servidor.
Monte o projeto com ferramentas de verdade
Leve o catálogo do projeto Aplicação com API para um projeto Vite com TypeScript, com scripts que qualquer pessoa do time consegue rodar.
- Crie o projeto com
npm create vite@latest, escolhendo a variante TypeScript, e mova o código do catálogo parasrc/ - Confira no
package.jsonos scriptsdevebuild, e adicione"typecheck": "tsc --noEmit" - Instale ESLint e Prettier como
devDependenciese crie os scriptslinteformat - Coloque o endereço da API em
VITE_API_URLnum.enve confira que.envenode_modulesestão no.gitignore - Faça commit do
package-lock.json, apaguenode_modulese reinstale comnpm ci - Rode
npm run builde abra a pastadist/para ver o que realmente vai para o navegador