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 dev executa vite. No build, 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 projeto
  • dayjs, que formata datas mostradas na tela
  • typescript, que confere os tipos
  • react, que desenha a interface no navegador
  • eslint, que procura problemas no código
  • prettier, 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 tsc falha e o vite build nem 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.

O que vai e o que não vai para o repositório
Arquivo ou pastaVai para o Git?Por quê
package.jsonSimLista o que o projeto precisa e os scripts
package-lock.jsonSimGarante 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
.envNãoPode 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.json do 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.

  1. Crie o projeto

    O comando faz algumas perguntas. Para começar, escolha Vanilla (sem framework) e a variante TypeScript.

    npm create vite@latest catalogo
  2. Entre na pasta e instale

    O npm install lê o package.json e baixa tudo para node_modules.

    cd catalogo
    npm install
  3. Ligue o servidor de desenvolvimento

    O terminal mostra um endereço como http://localhost:5173. Abra no navegador. Para desligar, Ctrl + C no terminal.

    npm run dev
  4. Edite e salve

    Mude um texto em src/main.ts e salve. A página atualiza sozinha em menos de um segundo, sem você recarregar.

Os dois modos do Vite: desenvolvimento e build

  1. src/ → Vite: salvou main.ts. Com npm run dev ligado, o Vite vigia a pasta src/. Você salvou um arquivo.
  2. 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.
  3. 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).
  4. src/ → Vite: npm run build. Hora de publicar. O build lê o projeto inteiro de uma vez.
  5. 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.
  6. Vite → dist/: index.html + assets/. O resultado vai para a pasta dist/: HTML, CSS e JavaScript prontos. É essa pasta que você publica.
  7. 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,00

Complete 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 catalogo
  • cd catalogo
  • npm install
  • npm run dev
  • npm run build
  • npm 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_aqui

Lendo 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.
  • dependencies vão para o navegador; devDependencies são ferramentas, instaladas com npm install -D.
  • node_modules nunca vai para o Git; o lockfile vai, e npm ci reproduz exatamente as mesmas versões.
  • O Vite atualiza a página na hora com npm run dev e gera a pasta dist/ para publicar com npm 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.

  1. Crie o projeto com npm create vite@latest, escolhendo a variante TypeScript, e mova o código do catálogo para src/
  2. Confira no package.json os scripts dev e build, e adicione "typecheck": "tsc --noEmit"
  3. Instale ESLint e Prettier como devDependencies e crie os scripts lint e format
  4. Coloque o endereço da API em VITE_API_URL num .env e confira que .env e node_modules estão no .gitignore
  5. Faça commit do package-lock.json, apague node_modules e reinstale com npm ci
  6. Rode npm run build e abra a pasta dist/ para ver o que realmente vai para o navegador

Referências

Cursos relacionados