Classes e módulos em JavaScript: npm e ferramentas

Uma classe descreve objetos com a mesma estrutura e o mesmo comportamento. Cada objeto criado a partir dela é uma instância. Use uma classe quando vários objetos precisarem das mesmas operações; um objeto simples costuma bastar para um único valor de configuração.

Dê a cada objeto seus próprios dados

Por convenção, nomes de classes usam PascalCase, como Rectangle. O constructor é executado cada vez que new cria uma instância. Dentro dele, this se refere ao novo objeto. Atribuir um valor a this.width armazena uma propriedade de instância; um parâmetro chamado apenas width é somente uma variável local.

class Rectangle {
  constructor(width, height) {
    this.width = width; // cm
    this.height = height;
  }
  area() {
    return this.width * this.height;
  }
  perimeter() {
    return 2 * (this.width + this.height);
  }
}
const a = new Rectangle(3, 4);
const b = new Rectangle(5, 2);
a.area();      // 12
a.perimeter(); // 14
b.area();      // 10

Em a.area(), o JavaScript chama o método com this definido como a. Multiplicar sua largura, 3 cm, por sua altura, 4 cm, resulta em 12 cm². O perímetro soma os dois lados diferentes e duplica essa soma, resultando em 14 cm. Alterar b.width modifica apenas b.

Métodos não têm a palavra-chave function nem vírgulas entre eles. Uma classe tem no máximo um construtor. Em uma classe sem extends, omiti-lo fornece um construtor padrão vazio. new retorna a instância criada automaticamente.

Um campo declara uma propriedade no corpo da classe: unit = "cm"; dá a cada instância seu próprio valor. label; começa como undefined. Em uma classe sem extends, campos de instância são inicializados antes da execução do corpo do construtor.

Leia e atribua valores por meio de acessores

Um método de leitura é executado quando uma propriedade é lida. Com get area() { return this.width * this.height; }, leia a.area sem parênteses. Essa é uma alternativa ao método acima, que usa a.area().

Um método de escrita é executado na atribuição e pode rejeitar entradas inválidas. Ele precisa de armazenamento separado: set width(value) { this.width = value; } chama a si mesmo repetidamente até ocorrer um estouro da pilha. Armazene o valor sob outro nome, como o campo privado #width.

Mantenha o objeto receptor ao passar um método

class Counter {
  count = 0;
  increment() { this.count++; }
}
const counter = new Counter();
const inc = counter.increment;
// inc(); // TypeError: this is undefined
const safeInc = () => counter.increment();
safeInc(); // counter.count is 1

Métodos de classe são executados em modo estrito. Uma chamada desvinculada não tem objeto receptor antes do ponto, portanto this é undefined. Quem chama uma função de retorno também pode fornecer um objeto receptor diferente. Uma função envoltória de seta preserva a chamada em counter; counter.increment.bind(counter) cria uma função vinculada. Um campo de função de seta, increment = () => { this.count++; };, também captura o this da instância.

Chamar Rectangle(3, 4) sem new lança um TypeError. Usar uma classe antes de sua declaração ser inicializada lança um ReferenceError. Nesse aspecto, classes diferem de declarações de função que podem ser chamadas antes no arquivo.

JSON preserva dados, não o comportamento de classes. JSON.stringify(a) salva suas propriedades públicas próprias de largura e altura. Analisar esse texto cria um objeto simples; reconstrua uma instância com new Rectangle(data.width, data.height) para usar seus métodos.

Um objeto pode oferecer uma pequena interface pública enquanto mantém seu armazenamento privado. Isso é encapsulamento. A interface decide quais alterações são válidas; a privacidade, por si só, não verifica um valor passado a um método de escrita público.

Coloque a validação na interface

Um campo privado começa com # e deve ser declarado no corpo da classe. O código dentro dessa classe o lê por meio de this.#target. O código externo não pode ler ou alterar t.#target: isso é um erro de sintaxe, não uma leitura de propriedade que retorna undefined.

class Thermostat {
  static MIN = 10;
  static MAX = 30;
  #target = 20;

  get target() { return this.#target; }
  set target(value) {
    if (!Number.isFinite(value) ||
        value < Thermostat.MIN ||
        value > Thermostat.MAX) {
      throw new RangeError("Target must be between 10 and 30 °C");
    }
    this.#target = value;
  }
}
const t = new Thermostat();
t.target = 22;
t.target; // 22
// t.target = 35; // throws RangeError

O método de leitura permite ler o valor sem expor o armazenamento. O método de escrita primeiro rejeita entradas não finitas ou não numéricas e depois valores fora do intervalo de 10 a 30 °C, incluindo os limites. Apenas um valor aceito chega à atribuição. Após uma tentativa rejeitada de definir 35 °C, a temperatura-alvo permanece em 22 °C. Uma cadeia numérica como "22" também falha em Number.isFinite.

Os métodos de leitura e de escrita usam #target, portanto atribuir um valor a t.target não chama o método de escrita recursivamente. Os nomes target e #target são distintos. Um sublinhado inicial, como em _target, apenas pede a outros programadores que tratem uma propriedade pública como interna; o JavaScript ainda permite acessá-la.

Campos privados não aparecem em Object.keys, for...in ou na serialização JSON. Esse termostato não tem campos públicos próprios, portanto JSON.stringify(t) produz "{}". Assim, salvar um objeto pode exigir um método público explícito que retorne os dados a serem salvos.

Mantenha funções auxiliares internas privadas

Um método como #check(value) { ... } pode conter etapas de validação e é chamado dentro da classe como this.#check(value). Ele não faz parte da interface pública. Dentro da classe, #target in obj verifica se um objeto possui esse campo privado.

Uma subclasse não pode usar diretamente o nome privado de sua classe pai. Ela pode usar o método de leitura ou de escrita público da classe pai, que é executado na classe que declarou o campo. Isso permite que a classe pai mantenha o controle de seu próprio estado.

Coloque o trabalho compartilhado na classe

Um membro estático pertence à classe. Thermostat.MIN é 10, enquanto t.MIN é undefined. Esses limites estáticos são campos públicos; static, por si só, não os torna somente de leitura.

class Tracked {
  static count = 0;
  constructor() { Tracked.count++; }
}
new Tracked();
new Tracked();
new Tracked();
Tracked.count; // 3

Cada construtor incrementa um contador no nível da classe. Um campo de instância, por sua vez, daria a cada objeto uma contagem separada. Um método fábrica estático, como static square(side) { return new Rectangle(side, side); }, pertence ao corpo de Rectangle e é chamado como Rectangle.square(5). Uma função auxiliar estática de comparação pode ser passada a sort quando recebe os objetos comparados como argumentos.

Dentro de um método estático, this é a classe na qual ele foi chamado; não é uma instância de retângulo com largura. Um bloco de inicialização static { ... } faz a configuração uma vez, quando a classe é definida, e pode acessar os membros privados dessa classe.

A herança modela uma relação é um. Um círculo é uma forma, portanto uma classe Circle pode herdar a descrição compartilhada de uma forma e fornecer seu próprio cálculo de área. Uma subclasse herda comportamento sem copiar todos os métodos para seu corpo.

Inicialize a classe pai primeiro

class Circle extends Shape torna Circle uma subclasse e Shape sua superclasse. No construtor de uma subclasse, super(...) chama o construtor da classe pai. Ele deve ser executado antes do primeiro uso de this. Uma subclasse sem construtor recebe um que encaminha seus argumentos à classe pai.

class Shape {
  constructor(name) { this.name = name; }
  area() { return 0; }
  describe() {
    return this.name + " with area " +
      this.area().toFixed(2) + " cm²";
  }
}
class Circle extends Shape {
  constructor(radius) {
    super("Circle");
    this.radius = radius;
  }
  area() { return Math.PI * this.radius ** 2; }
}
class Rectangle extends Shape {
  constructor(width, height) {
    super("Rectangle");
    this.width = width;
    this.height = height;
  }
  area() { return this.width * this.height; }
}

Chamar new Circle(2).describe() produz "Circle with area 12.57 cm²". Primeiro, super define o nome. O círculo armazena seu raio. Então, o describe() herdado chama this.area(), que encontra o método do círculo. toFixed(2) formata o resultado para exibição. new Rectangle(3, 4).describe() produz "Rectangle with area 12.00 cm²".

Sobrescreva ou amplie um método

Uma subclasse sobrescreve um método ao declarar o mesmo nome. Ela pode chamar a versão da classe pai por meio de super.methodName().

class Square extends Rectangle {
  constructor(side) {
    super(side, side);
    this.name = "Square";
  }
  describe() {
    return super.describe() +
      " (all sides " + this.width + " cm)";
  }
}
new Square(5).describe();
// "Square with area 25.00 cm² (all sides 5 cm)"

super(side, side) inicializa largura e altura iguais. O método de área herdado as multiplica, e o método sobrescrito acrescenta informações à descrição herdada. Esquecer argumentos necessários à classe pai pode deixar suas propriedades como undefined; chamar super() não basta se a classe pai precisar de valores.

Polimorfismo significa que a mesma chamada pode selecionar comportamentos diferentes. Um laço pode chamar s.describe() em círculos e retângulos; cada descrição chama o area() apropriado. Adicionar uma forma com seu próprio método de área não exige um novo caso nesse laço.

new Circle(2) instanceof Circle e new Circle(2) instanceof Shape são ambos verdadeiros. Membros estáticos também são herdados. A relação de uma instância com uma classe segue sua cadeia de protótipos, que é o que instanceof normalmente verifica.

Escolha uma relação adequada

Uma classe pode estender apenas uma classe pai. Para uma relação tem um, use composição: um carro tem um motor e pede que this.engine.start() execute uma tarefa. Compartilhar apenas uma função auxiliar não é motivo para afirmar que uma classe sem relação é um tipo de outra. Um mixin copia um grupo de métodos para um protótipo, por exemplo, com Object.assign(Rectangle.prototype, serializable). Cadeias profundas de classes pai podem dificultar o acompanhamento de alterações.

Classes nativas também podem ser estendidas. Um construtor de ValidationError extends Error chama super(message), define this.name = "ValidationError" e pode armazenar this.field = field. Um bloco catch pode usar err instanceof ValidationError para tratar essa falha de forma diferente e ler a mensagem herdada.

Um objeto tem uma ligação oculta com outro objeto, seu protótipo, ou com null. A leitura de uma propriedade ausente segue essa ligação. O JavaScript continua procurando até encontrar a propriedade ou chegar a null; uma busca sem sucesso retorna undefined.

Distinga valores armazenados e herdados

const defaults = { theme: "light", fontSize: 16 };
const settings = Object.create(defaults);
settings.fontSize = 18;
settings.theme;                   // "light"
settings.fontSize;                // 18
defaults.fontSize;                // 16
Object.hasOwn(settings, "theme"); // false
"theme" in settings;              // true
Object.keys(settings);            // ["fontSize"]

Object.create(defaults) cria um objeto vazio cujo protótipo é defaults. Atribuir um valor a fontSize cria uma propriedade própria que sombreia o valor herdado. Isso deixa defaults.fontSize inalterado. Após delete settings.fontSize, a busca volta a alcançar o valor herdado 16.

Uma propriedade própria ausente ainda pode existir na cadeia. Métodos de classe não são enumeráveis, então for...in normalmente não os lista. Use Object.getPrototypeOf(settings) para ler seu protótipo. Prefira esses métodos de Object ao acessor antigo __proto__.

Veja como classes compartilham métodos

Para uma instância de retângulo r, Object.getPrototypeOf(r) === Rectangle.prototype é verdadeiro. Sua largura é uma propriedade própria, enquanto area normalmente fica armazenado em Rectangle.prototype. Object.hasOwn(r, "area") é falso, embora r.area() funcione. Um campo de função de seta é diferente: ele cria uma propriedade própria de função em cada instância.

Um método herdado ainda recebe como this o objeto antes do ponto. Assim, o método de área compartilhado pode ler dimensões diferentes para cada retângulo sem armazenar um método separado em cada objeto.

Para a hierarquia de formas, a busca segue:

circle -> Circle.prototype -> Shape.prototype
       -> Object.prototype -> null

O método de área do círculo é encontrado primeiro. Sua descrição vem de Shape.prototype, e toString pode vir de Object.prototype. Shape.prototype na cadeia também explica por que circle instanceof Shape é verdadeiro.

O nome Rectangle.prototype significa o protótipo dado às instâncias de retângulo. Ele não designa o protótipo oculto da própria função Rectangle; para essa classe, ele é Shape quando ela estende Shape, ou Function.prototype para uma classe sem superclasse.

Reconheça código antigo com funções construtoras

function Rectangle(width, height) {
  this.width = width;
  this.height = height;
}
Rectangle.prototype.area = function () {
  return this.width * this.height;
};

Funções construtoras usam a mesma estrutura básica de instância e protótipo. A sintaxe de classe acrescenta regras: new é obrigatório, o corpo opera em modo estrito, os métodos não são enumeráveis e membros privados estão disponíveis. typeof Rectangle é "function" em ambas as formas.

Vetores encontram map em Array.prototype; métodos de cadeias de caracteres vêm de String.prototype. Evite adicionar métodos personalizados a protótipos nativos: bibliotecas e padrões futuros podem usar os mesmos nomes com comportamento diferente. O uso existente de flatten em uma biblioteca ajudou a levar à escolha de flat como nome do método padrão de vetor.

A atribuição comum a uma propriedade de dados cria ou altera uma propriedade própria, mas um método de escrita herdado pode interceptar a atribuição. Alterar o protótipo de um objeto existente com Object.setPrototypeOf é permitido, mas pode prejudicar o desempenho; escolha o protótipo ao criar o objeto.

Um módulo ES tem seu próprio escopo. Suas declarações de nível superior permanecem dentro do arquivo, a menos que sejam exportadas. Os importadores solicitam recursos específicos, tornando as dependências visíveis sem colocar tudo em variáveis globais.

Use a forma correspondente à exportação

// geometry.js
export const round2 = (n) => Math.round(n * 100) / 100;
export function circleArea(r) {
  return Math.PI * r * r;
}

// shapes.js
import { circleArea, round2 } from "./geometry.js";
export default class Circle {
  constructor(r) { this.r = r; }
  area() { return round2(circleArea(this.r)); }
}

// main.js
import Circle from "./shapes.js";
console.log(new Circle(3).area()); // 28.27

O módulo de entrada importa uma classe. O módulo da classe importa duas funções auxiliares. Para um raio de 3 cm, a área é aproximadamente 28,274 cm²; a função auxiliar de arredondamento produz 28,27. O módulo de entrada não ganha acesso automaticamente às funções auxiliares usadas dentro de outro módulo.

Um módulo pode ter muitas exportações nomeadas, mas no máximo uma exportação padrão. Importações nomeadas usam o nome exportado entre chaves; o nome local de uma importação padrão é escolhido por quem importa. Escrever import { Circle } não solicita a exportação padrão, mesmo quando a classe exportada se chama Circle.

Renomeie, agrupe e reexporte

import { circleArea as areaOfCircle } from "./geometry.js"; dá a um recurso importado um nome local diferente. export { circleArea as area }; altera seu nome exportado. Uma lista de exportação também pode expor declarações feitas anteriormente no arquivo.

import * as geometry from "./geometry.js"; cria um objeto de espaço de nomes do módulo. Chame geometry.circleArea(3). Um espaço de nomes inclui uma exportação padrão sob a propriedade default, se o módulo tiver uma.

Um arquivo pode reunir exportações de outros arquivos: export { circleArea } from "./geometry.js"; encaminha uma exportação nomeada. export * from "./geometry.js"; encaminha exportações nomeadas, mas não encaminha a exportação padrão desse módulo.

Entenda a avaliação compartilhada e as vinculações ativas

Módulos são executados em modo estrito e têm undefined como this no nível superior. As dependências são avaliadas antes do corpo do módulo que as importa. Importar o mesmo módulo resolvido de vários arquivos reutiliza um único módulo avaliado e seu estado.

Suponha que um módulo exporte let count = 0 e que increment() o altere. Depois que um importador chama increment(), seu count importado tem valor 1. Importações são vinculações ativas, não cópias instantâneas. O importador não pode reatribuir a própria vinculação. Se uma exportação for um objeto, ainda será possível alterar uma de suas propriedades, e outros importadores verão a alteração.

Mantenha declarações de importação estática no nível superior do módulo. Uma importação estática dentro de um if ou de uma função é um erro de sintaxe; import() dinâmico permite o carregamento posterior. Inclua .js em caminhos relativos de módulos ES no navegador e no Node.js: esses carregadores não adicionam a extensão. Um erro de caminho ou uma incompatibilidade entre exportação nomeada e padrão impede o carregamento do módulo, então corrija a importação antes de procurar um erro no código que deveria ser executado depois.

A mesma sintaxe de módulos ES é executada em um navegador e no Node.js. Cada ambiente ainda precisa saber que um arquivo é um módulo, e cada um tem sua própria maneira de resolver os caminhos solicitados.

Inicie um módulo no navegador

<script type="module" src="main.js"></script>

Carregue apenas o módulo de entrada com uma tag script. Suas importações buscam os outros arquivos automaticamente. Scripts de módulo sem async têm execução adiada: são executados após a análise do HTML, na ordem do documento. Os elementos da página que eles acessam estarão disponíveis nesse momento.

Sirva a pasta por HTTP com um servidor local, como python3 -m http.server ou npx serve, e abra seu endereço localhost. Abrir o HTML a partir do disco geralmente faz as requisições de módulos falharem devido às regras de segurança do navegador. O servidor também deve retornar JavaScript com um tipo MIME adequado, como text/javascript.

Declarações de módulo não se tornam globais. Um tratador incorporado ao HTML, como onclick="save()", não consegue encontrar uma função local de um módulo. Registre o tratador a partir do JavaScript:

const button = document.querySelector("#save");
function save() { console.log("Saved"); }
button.addEventListener("click", save);

Resolva caminhos e nomes de pacotes

O especificador de módulo é a cadeia de caracteres que nomeia o módulo. ./geometry.js é relativo ao arquivo que importa; ../geometry.js sobe uma pasta. Um caminho que começa com / parte da raiz do site, enquanto uma URL HTTPS completa indica sua localização completa.

Um nome simples como "date-fns" não tem prefixo de caminho. Um navegador não consegue procurá-lo em node_modules. Um mapa de importações colocado antes dos scripts de módulo associa um nome simples a uma URL. Um servidor de desenvolvimento ou empacotador pode, por sua vez, resolver os pacotes instalados e prepará-los para o navegador. Instalar um pacote, por si só, não altera o carregador do navegador.

Torne explícito o formato de módulo do Node.js

O Node.js lê type do package.json pai mais próximo. Sem um tipo explícito, versões atuais conseguem detectar a sintaxe de módulo ES em um arquivo .js que seria ambíguo. Defina "type": "module" em um novo projeto de módulos ES para que as ferramentas concordem sobre o formato pretendido. As extensões .mjs e .cjs prevalecem sobre essa configuração.

Com os três arquivos do exemplo do círculo e { "type": "module" }, node main.js exibe 28.27. Os mesmos arquivos funcionam por meio de um script de módulo no navegador servido por HTTP.

Reconheça CommonJS e módulos nativos

CommonJS é o sistema de módulos mais antigo do Node.js. Ele usa require() para carregar de forma síncrona e module.exports para fornecer valores. Um módulo ES pode importar module.exports de um pacote CommonJS como exportação padrão. O Node.js atual também pode carregar com require grafos de módulos ES síncronos; await no nível superior desse grafo impede o carregamento síncrono.

Em um módulo ES, use import { readFile } from "node:fs/promises"; para um módulo nativo do Node.js. require, module e __dirname são variáveis CommonJS, não globais de módulos ES. import.meta.url fornece a URL do módulo; versões recentes do Node.js também fornecem import.meta.dirname para módulos em arquivos locais.

Se uma instrução de importação for rejeitada por estar fora de um módulo, examine a configuração do carregador: type="module" no HTML do navegador, ou o tipo de pacote ou a extensão no Node.js.

Uma importação estática declara uma dependência necessária como parte do carregamento de um módulo. Uma importação dinâmica é uma expressão: ela inicia o carregamento quando a execução chega a ela e retorna uma promessa. Use-a para um recurso que muitas visitas nunca precisam usar.

Aguarde o objeto de espaço de nomes

const button = document.querySelector("#show-chart");
button.addEventListener("click", async () => {
  try {
    const { drawChart } = await import("./chart.js");
    drawChart(measurements);
  } catch (err) {
    console.error("Could not load the chart module", err);
  }
});

Aqui, measurements são os dados que a página coletou. O primeiro clique carrega o módulo de gráfico e chama sua função exportada. Cliques posteriores reutilizam o módulo avaliado. A promessa pode ser rejeitada por um erro de carregamento ou avaliação, portanto o tratador captura esse erro.

import("./chart.js").drawChart tenta ler uma propriedade da promessa, não do módulo carregado. Aguarde a promessa ou use .then. Para uma exportação padrão, acesse a propriedade default do espaço de nomes: const { default: Chart } = await import("./chart.js");. Diferentemente de uma declaração estática, essa expressão pode ocorrer dentro de uma função ou condição, e seu caminho pode ser calculado em tempo de execução.

Aguarde durante a configuração do módulo

Um módulo ES pode usar await no nível superior fora de uma função:

const response = await fetch("./config.json");
export const config = await response.json();

Módulos que dependem desse módulo aguardam o fim de sua avaliação antes de executar seus próprios corpos. Módulos independentes podem continuar. Portanto, uma requisição lenta de configuração atrasa seus dependentes, não necessariamente todas as partes do programa. Scripts clássicos e CommonJS não permitem await no nível superior; use esse recurso de módulo para configurações de que seus dependentes realmente precisam primeiro.

Dê a cada módulo uma função clara

Uma aplicação de tarefas pode usar estes limites:

Os módulos de dados e armazenamento não importam a interface do usuário. Eles podem ser testados e reutilizados sem criar elementos de página. Manter cálculo e armazenamento fora dos tratadores de eventos também facilita a localização de falhas.

O estado privado de nível superior é compartilhado entre os importadores. Em let nextId = 1; export function createId() { return nextId++; }, a variável permanece privada, enquanto a função oferece acesso controlado. Dois importadores que a chamam uma vez recebem 1 e 2, não dois contadores separados começando em 1.

Controle o trabalho no momento da importação

import "./setup.js"; é uma importação por efeito colateral: ela carrega e avalia o módulo sem solicitar nomes locais. Efeitos colaterais podem ser úteis para configuração, mas um módulo reutilizável é mais fácil de testar quando seu nível superior define recursos e suas funções iniciam o trabalho explicitamente.

Um arquivo agregador reúne reexportações. Ele pode simplificar uma interface, mas arquivos agregadores grandes podem trazer código extra e ocultar um ciclo. Uma dependência circular ocorre quando módulos dependem uns dos outros, diretamente ou por meio de outros módulos. Um ciclo pode funcionar, mas ler uma vinculação antes de seu módulo exportador inicializá-la causa um ReferenceError. Mova as definições compartilhadas para um terceiro módulo importado por ambos os lados para eliminar esse ciclo de dependência.

npm é o gerenciador de pacotes fornecido com o Node.js. O nome se refere tanto a uma ferramenta de linha de comando quanto a seu registro público de pacotes. Um pacote é uma pasta descrita por package.json; a raiz de um projeto é a pasta que contém esse arquivo.

Crie a descrição do projeto

Execute node -v e npm -v para verificar as ferramentas instaladas. Vá para a pasta desejada do projeto antes de executar npm init. O comando interativo faz perguntas; npm init -y aceita os padrões. Depois, edite o arquivo para descrever o projeto.

{
  "name": "shape-lab",
  "version": "1.0.0",
  "private": true,
  "type": "module",
  "scripts": {
    "start": "node src/main.js",
    "test": "node --test",
    "lint": "eslint ."
  },
  "dependencies": {},
  "devDependencies": {}
}

Isso é JSON, não um literal de objeto JavaScript. Chaves e cadeias de caracteres usam aspas duplas. Comentários e vírgulas finais são inválidos. Um erro de análise sintática pode interromper o npm antes que ele execute qualquer comando.

O name usa letras minúsculas e é compatível com URLs; nomes de pacotes publicados têm no máximo 214 caracteres. version descreve este projeto, não sua versão do Node.js. private: true evita a publicação acidental no npm. type: "module" faz o Node.js carregar os arquivos .js do pacote como módulos ES.

Pacotes publicados podem usar main e exports para definir pontos de entrada para seus usuários. Uma entrada opcional engines, como { "node": ">=22" }, informa as versões do Node.js aceitas. Leia esses requisitos quando um projeto falhar em uma instalação mais antiga.

Use scripts como menu de tarefas

npm run lista os scripts disponíveis. Neste exemplo, npm run lint executa eslint ., npm start executa a aplicação e npm test executa o executor de testes. start e test têm essas formas curtas; outros nomes de tarefa normalmente usam npm run.

O npm adiciona temporariamente o diretório node_modules/.bin do projeto ao caminho de busca de comandos. Assim, uma ferramenta instalada localmente pode ser nomeada diretamente em um script. Todas as pessoas que usam o projeto executam a mesma ferramenta registrada em vez de depender de uma instalação global.

Argumentos adicionais vêm após --: npm run lint -- --fix passa --fix ao ESLint. O script dá à tarefa um nome estável mesmo que a equipe mude a ferramenta por trás dela. Comece pelo campo scripts ao aprender a trabalhar em um projeto desconhecido.

Leia números de versão

O versionamento semântico usa MAJOR.MINOR.PATCH. A partir de 2.4.1, uma correção de erro compatível torna-se 2.4.2; um recurso compatível torna-se 2.5.0; uma mudança incompatível torna-se 3.0.0. Uma atualização major pode exigir alterações no código que usa o pacote. Antes de 1.0.0, um projeto está em desenvolvimento inicial e as versões podem mudar mais livremente.

Execute um comando de pacote ocasional

npx serve executa o comando instalado se estiver disponível localmente. Caso contrário, o npx pode pedir para baixar o pacote temporariamente e executá-lo. Isso é útil para uma ferramenta que não precisa se tornar uma dependência permanente do projeto. Verifique o nome exato do pacote e a confiabilidade do código antes de instalá-lo ou executá-lo: comandos de pacotes e scripts de instalação podem ser executados com suas permissões.

Um comando executado na pasta errada pode falhar porque package.json está ausente, ou uma instalação pode criar arquivos de pacote em um local não desejado. Verifique primeiro a pasta atual. Mantenha os scripts compreensíveis e evite truques de comando específicos de um sistema operacional quando o projeto precisar funcionar em vários sistemas.

Uma dependência é código do qual um projeto depende. O npm registra dependências diretas em package.json, instala pacotes em node_modules e registra a árvore exata de dependências instaladas em package-lock.json.

Separe o código do produto das ferramentas de desenvolvimento

npm install date-fns adiciona um pacote de execução a dependencies. npm install --save-dev eslint adiciona uma ferramenta de desenvolvimento a devDependencies; -D é a forma curta. Analisadores e formatadores de código, executores de testes, empacotadores e TypeScript normalmente pertencem à lista de desenvolvimento.

Quando outro projeto instala um pacote publicado, o npm instala as dependências desse pacote, mas não suas dependências de desenvolvimento. Uma aplicação para navegador ainda pode incluir dependências de execução em seus arquivos finais, embora a própria ferramenta de compilação seja uma devDependency.

npm install sem nome de pacote instala as dependências listadas para o projeto. npm uninstall <package> remove um pacote e seu registro. Após instalar date-fns, o Node.js e ferramentas de compilação conseguem resolver import { format } from "date-fns";. Um navegador sem essas ferramentas ainda precisa de um recurso para resolver o nome, como um mapa de importações ou um servidor de desenvolvimento.

Leia o intervalo permitido

O acento circunflexo é o padrão usual do npm. Para versões iguais ou superiores a 1.0.0, ele permite atualizações minor e patch compatíveis. Abaixo de 1.0.0, ele é mais restritivo. Para ^2.3.0, 2.3.5 e 2.9.0 são aceitas; 2.2.9 é antiga demais e 3.0.0 ultrapassa o limite major.

Um intervalo permitido não identifica uma única versão instalada. O arquivo de travamento faz isso, incluindo as dependências transitivas, que são os pacotes de que seus pacotes escolhidos precisam.

Recrie uma instalação

Compartilhe package.json e package-lock.json com o projeto. Deixe o npm manter o arquivo de travamento. A pasta gerada node_modules pode ser recriada e não é o arquivo a ser compartilhado.

Use npm install durante o desenvolvimento, quando os registros de dependências podem mudar. Use npm ci para uma instalação limpa e reproduzível: ele exige o arquivo de travamento, remove node_modules existente, instala a árvore registrada e não reescreve nenhum dos dois arquivos de pacote. Ele falha se o arquivo de pacote e o arquivo de travamento divergirem. Corrija essa divergência deliberadamente durante o desenvolvimento; excluir o arquivo de travamento pode alterar silenciosamente muitas versões.

Atualize por um motivo

npm outdated compara as versões atual, desejada (wanted) e mais recente (latest). A desejada é a versão mais recente permitida pelo intervalo declarado; a mais recente pode ser uma versão major fora desse intervalo. npm update atualiza dentro dos intervalos e registra a árvore resultante. Para avançar deliberadamente para uma nova versão major, leia o histórico de alterações, execute npm install <package>@latest e verifique o projeto com seus testes.

Instale ferramentas de projeto localmente para que suas versões sejam registradas. Antes de adicionar outra dependência, verifique manutenção, adoção, licença e se um recurso nativo já resolve o problema. structuredClone() atende às necessidades de cópia profunda compatíveis; Intl.DateTimeFormat formata datas sem um pacote de datas.

npm audit informa vulnerabilidades conhecidas em versões instaladas. Leia o relatório para entender o código afetado e seu uso. npm audit fix pode aplicar correções compatíveis, mas não comprova que toda vulnerabilidade foi resolvida nem que uma atualização preserva o comportamento do projeto.

Um analisador de código lê o código-fonte sem executá-lo e informa possíveis erros ou padrões arriscados. Um formatador de código reescreve a disposição de forma consistente. ESLint e Prettier frequentemente trabalham juntos porque essas tarefas resolvem problemas diferentes.

Configure as verificações

npm init @eslint/config@latest faz perguntas sobre o projeto, instala pacotes de desenvolvimento e cria um arquivo de configuração. O ESLint atual usa configuração plana, geralmente em eslint.config.js.

import js from "@eslint/js";
import globals from "globals";

export default [
  js.configs.recommended,
  {
    languageOptions: { globals: globals.browser },
    rules: {
      eqeqeq: "error",
      "no-unused-vars": "warn",
    },
  },
];

A configuração recomendada ativa regras para detectar erros. As variáveis globais do navegador informam ao ESLint que nomes como document existem. Isso evita tratar um recurso real do ambiente como um nome não definido.

As severidades das regras são "off", "warn" e "error", também escritas como 0, 1 e 2. Erros causam um código de saída de falha; avisos por si só não fazem o comando falhar por padrão. Um aviso ainda é uma informação a ser lida, mesmo que o script termine com sucesso.

Leia um relatório de análise

function total(items) {
  let sum = 0;
  let unused = 5;
  for (const item of items) {
    if (item.quantity == "2") sum += item.price;
  }
  return summ;
}

Com a configuração acima, são informados cinco problemas. total nunca é usada. sum é atualizada, mas seu valor nunca é usado além dessas atualizações. unused não é usada. A regra eqeqeq sinaliza ==, e no-undef detecta summ, escrito incorretamente. Chamar essa função causaria uma falha nesse nome não definido, mas o analisador consegue encontrá-lo sem uma chamada.

Comece pelo nome e pela localização da regra no relatório. Corrija o comportamento pretendido e execute o comando novamente. npm run lint -- --fix solicita correções automáticas seguras quando o projeto tem um script lint. Ele não consegue decidir a lógica de negócio correta para cada aviso. Desative uma regra em uma linha somente quando houver um motivo e registre esse motivo ao lado do comentário.

Deixe a formatação com um único formatador

npm install --save-dev --save-exact prettier
npx prettier . --write
npx prettier . --check

--write altera arquivos; --check informa diferenças de formatação sem alterá-los. Com os padrões, const point={x:1,y:2} torna-se const point = { x: 1, y: 2 };. Opções como "singleQuote": true ficam em .prettierrc.

As regras recomendadas do ESLint não impõem a formatação do Prettier, portanto essa configuração evita conflitos de formatação. Se outra configuração do ESLint adicionar regras de estilo conflitantes, eslint-config-prettier as desativa. Executar dois formatadores concorrentes pode fazer os arquivos mudarem continuamente de um formato para outro.

Adicione scripts lint e format para facilitar a repetição das verificações. Extensões do editor podem mostrar diagnósticos enquanto você digita e formatar ao salvar, depois de configuradas. Ambas as ferramentas ignoram node_modules por padrão; adicione resultados gerados, como dist, às configurações de exclusão apropriadas. Uma função sem avisos de análise ainda pode calcular o perímetro quando deveria calcular a área; o comportamento precisa de testes.

Um navegador pode carregar alguns módulos ES diretamente, mas projetos maiores também usam pacotes instalados e arquivos que precisam de transformação. Um servidor de desenvolvimento prepara arquivos enquanto você edita. Um empacotador segue as dependências para produzir arquivos adequados ao lançamento.

Percorra o ciclo do Vite

npm create vite@latest shape-lab
cd shape-lab
npm install
npm run dev
npm run build
npm run preview

Escolha o modelo Vanilla JavaScript para este projeto. O gerador fornece scripts de desenvolvimento e compilação. npm run dev exibe um endereço local, geralmente http://localhost:5173. Abra esse endereço enquanto edita. No Vite, index.html é o ponto de entrada e normalmente carrega /src/main.js com um script de módulo.

O servidor de desenvolvimento resolve nomes de pacotes e transforma arquivos conforme necessário. Salvar um arquivo aciona uma atualização. A substituição de módulos em tempo de execução, ou HMR, substitui um módulo alterado na página em execução; atualizações compatíveis podem preservar o estado em vez de forçar um recarregamento completo.

npm run build escreve o resultado otimizado em dist. npm run preview serve esse resultado localmente para que você possa verificar a compilação real para produção. A pré-visualização precisa de uma compilação existente e não cria uma nova. Edite os arquivos de origem, pois outra compilação substitui o resultado gerado.

Entenda as mudanças para produção

Por exemplo, um módulo de funções auxiliares pode exportar tanto formatArea quanto formatVolume. Se apenas formatArea for usada e a remoção do outro código for segura, a eliminação de código não utilizado pode omitir formatVolume. Importações e exportações estáticas tornam as dependências visíveis. Efeitos colaterais no nível superior de um módulo podem precisar permanecer mesmo quando nenhuma de suas exportações é usada.

Um import() dinâmico fornece à ferramenta de compilação um ponto para carregamento posterior. Ferramentas de compilação podem criar blocos separados para ele; a organização dos blocos depende da compilação, portanto um módulo de origem nem sempre se torna exatamente um arquivo de saída.

Um nome como assets/index-4f2a9c1b.js muda com seu conteúdo, permitindo caches de navegador duradouros sem servir um arquivo antigo após uma atualização. Um mapa de código-fonte liga locais gerados às linhas originais do código-fonte, facilitando rastreamentos de pilha e depuração quando os mapas estão disponíveis.

Inclua recursos e configuração pública

O Vite também processa recursos: import "./style.css"; inclui estilos, e import logoUrl from "./logo.png"; fornece a URL final da imagem. A compilação pode atualizar essas referências para corresponder aos nomes de arquivo gerados.

Leia informações de modo por meio de import.meta.env.MODE. Seus valores padrão são "development" para desenvolvimento e "production" para uma compilação; um modo personalizado pode usar outro nome. Valores de ambiente personalizados que começam com VITE_ são expostos ao código do navegador por padrão. Tudo o que é enviado ao navegador é público: mantenha chaves secretas e senhas em um servidor, fora do código do navegador e das variáveis de ambiente expostas.

Não verifique apenas a página de desenvolvimento. Compile e faça a pré-visualização antes do lançamento para encontrar problemas no resultado transformado e nos caminhos de recursos. Abrir dist/index.html diretamente do disco não reproduz a disponibilização do site por HTTP. Uma página pequena com alguns módulos simples pode precisar apenas de um servidor estático, sem uma ferramenta completa de compilação.

Um teste automatizado executa código com entradas conhecidas e verifica o resultado usando asserções. Um teste unitário se concentra em uma pequena parte, como uma função ou método. O executor encontra testes, executa-os, informa falhas e termina sem sucesso quando um teste falha.

Preparar, agir, verificar

Prepare a entrada, aja chamando o código e verifique o resultado esperado. Um nome útil de teste descreve o comportamento. Para uma classe de retângulo cujo construtor rejeita um lado negativo:

import { test } from "node:test";
import assert from "node:assert/strict";
import { Rectangle } from "./rectangle.js";

test("area multiplies width by height", () => {
  assert.equal(new Rectangle(3, 4).area(), 12);
});
test("rejects a negative width", () => {
  assert.throws(() => new Rectangle(-1, 4), RangeError);
});

A primeira asserção verifica 12 cm², um resultado conhecido independentemente. A segunda passa uma função a assert.throws para que a asserção possa observar o erro. Executar node --test encontra nomes como rectangle.test.js; um script de pacote "test": "node --test" permite usar npm test.

O modo estrito de asserções usa Object.is em assert.equal, sem coerção de tipos. assert.deepEqual compara o conteúdo de objetos e vetores. Vetores distintos que contêm os mesmos valores não são o mesmo objeto, portanto uma comparação estrita de identidade não é a verificação adequada para conteúdos iguais.

Use ideias equivalentes no Vitest

import { describe, it, expect } from "vitest";
import { Rectangle } from "./rectangle.js";

describe("Rectangle", () => {
  it("computes the area", () => {
    expect(new Rectangle(3, 4).area()).toBe(12);
  });
  it("rejects a negative width", () => {
    expect(() => new Rectangle(-1, 4)).toThrow(RangeError);
  });
});

O Vitest usa describe para agrupamento e it para testes individuais. Execute npx vitest para monitorar alterações ou npx vitest run para uma única execução. O Jest oferece um estilo semelhante. Use toEqual para conteúdos e toBe para identidade ou valores primitivos.

Inclua valores-limite e limites numéricos

Teste os limites exatos de um intervalo permitido e também entradas imediatamente fora dele. Um termostato que aceita de 10 a 30 °C precisa de testes que aceitem 10 e 30, além de testes que rejeitem 9,5 e 30,5. Adicione verificações separadas para valores não numéricos e não finitos se a interface os rejeitar. Testes não devem depender de um objeto modificado por um teste anterior nem da ordem de execução.

A aritmética em ponto flutuante pode não corresponder exatamente a um decimal escrito: 0.1 + 0.2 é 0.30000000000000004. Para usar uma tolerância apropriada, use assert.ok(Math.abs(actual - expected) < 1e-9). Um círculo de raio 3 tem área de aproximadamente 28,274333882 cm²; toBeCloseTo(28.27, 2) do Vitest verifica a proximidade nessa precisão decimal. Escolha a tolerância de acordo com o que o teste precisa estabelecer.

Aprenda com uma falha

Leia o comportamento indicado no nome, os valores esperado e obtido e a localização no código-fonte. Decida se a implementação ou a expectativa do teste está errada. No desenvolvimento orientado a testes, escreva um teste que falha, implemente o suficiente para fazê-lo passar e depois melhore o código mantendo os testes aprovados.

Exporte a lógica dos módulos e passe entradas como argumentos. Assim, um tratador de eventos pode reunir dados da página e chamar essa lógica, em vez de misturar cálculos ao trabalho com o DOM. Código dependente do DOM pode usar um navegador simulado, como jsdom. Aguarde o trabalho assíncrono em um teste assíncrono para que ele não termine antes de suas verificações. Um teste que apenas repete a fórmula da implementação pode repetir seu erro; use o comportamento esperado e exemplos independentes.

O TypeScript acrescenta sintaxe de tipos estáticos ao JavaScript. Um tipo descreve que tipo de valor o código espera. O verificador usa essas descrições antes da execução do programa, o que pode revelar erros antes que um usuário os encontre.

Verifique uma chamada antes da execução

function area(width: number, height: number): number {
  return width * height;
}
area(3, "4"); // type error: the second argument is a string

Ambos os parâmetros devem ser números. O valor escrito "4" é uma cadeia de caracteres, portanto o verificador informa a incompatibilidade. O JavaScript puro faria a coerção dessa cadeia na multiplicação: 3 * "4" produz 12. Na adição, 3 + "4" produz "34". Um erro de tipo identifica uma incompatibilidade nas entradas pretendidas mesmo quando o JavaScript poderia executar a expressão.

Uma interface descreve a estrutura de um objeto:

interface Shape {
  name: string;
  area(): number;
}

Uma classe declarada com implements Shape deve fornecer as propriedades e os métodos especificados com tipos compatíveis. O verificador também pode detectar propriedades escritas incorretamente, quantidades incorretas de argumentos e possíveis valores undefined quando a verificação estrita está ativada.

Separe a verificação da remoção de tipos

As configurações de um projeto TypeScript ficam em tsconfig.json. Uma compilação do Vite não estabelece, por si só, que todos os tipos estão corretos. Projetos geralmente executam tsc --noEmit separadamente. O Node.js atual pode executar arquivos .ts compatíveis diretamente, mas sua remoção de tipos também não os verifica.

Mantenha verificações em tempo de execução nos pontos de entrada de dados

Anotações de tipo são removidas antes da execução. Declarar o tipo esperado de dados de fetch() ou JSON.parse() não verifica o valor real. Verifique dados externos no código em execução antes de usá-los. Um servidor pode enviar uma cadeia de caracteres mesmo quando uma declaração de tipo diz que um campo é numérico.

private e readonly do TypeScript são restrições do verificador; eles não fornecem a privacidade de # do JavaScript em tempo de execução. Campos privados do JavaScript continuam protegidos quando o programa é executado. O TypeScript também não faz um programa executar mais rapidamente nem comprova que seus cálculos estão corretos.

O tipo any desativa verificações úteis para um valor. Ele pode silenciar um erro enquanto permite que o erro original permaneça. Corrigir uma suposição incorreta ou adicionar uma verificação real dos dados fornece melhores informações ao verificador.

Adote-o em etapas viáveis

Um arquivo JavaScript pode começar com // @ts-check e usar JSDoc como /** @param {number} width */ para receber verificações em editores compatíveis sem se tornar um arquivo .ts. Um projeto pode depois renomear arquivos um de cada vez. Bibliotecas podem fornecer definições de tipo .d.ts; definições da comunidade são frequentemente distribuídas em @types/....

Projetos maiores e duradouros ganham interfaces mais claras, refatoração mais segura e melhor preenchimento automático no editor. Um script pequeno talvez ainda não justifique outra etapa de compilação e uma nova sintaxe. Testes continuam úteis em ambos os casos: uma função de área com tipos corretos ainda pode retornar um cálculo numérico errado.

Uma biblioteca fornece código que seu programa chama. Um framework fornece uma estrutura de aplicação e chama seu código nos momentos certos. Essa mudança no controle ajuda a coordenar interfaces maiores, mas continua baseada em JavaScript, módulos e um conjunto de ferramentas de projeto.

Organize uma interface em componentes

React, Vue, Svelte e Angular organizam interfaces de usuário com componentes: partes reutilizáveis, como uma barra de navegação ou um item de tarefa. Um componente combina marcação e comportamento, muitas vezes com estilos. Quando seu estado muda, o sistema de interface coordena as atualizações pertinentes da página.

Metaframeworks como Next.js, Nuxt, SvelteKit e Astro acrescentam uma estrutura mais ampla, incluindo roteamento, renderização no servidor e suporte à compilação. Seus recursos específicos diferem. Conhecer funções, eventos, código assíncrono e limites entre módulos em JavaScript ajuda no aprendizado de qualquer um deles.

Uma página com alguns recursos interativos independentes pode ser clara com JavaScript puro. Um framework se torna útil quando muitas visões precisam compartilhar dados que mudam. Escolha-o para essa necessidade em vez de presumir que toda página exige o maior conjunto de ferramentas.

Acompanhe como as ferramentas trabalham juntas

Pacotes de frameworks são instalados pelo npm e importados como módulos. Ferramentas de compilação transformam sintaxe como JSX ou arquivos específicos de frameworks. O TypeScript pode verificar interfaces entre partes. Análise, formatação e testes mantêm suas funções distintas independentemente da escolha para a interface do usuário.

Inicie um projeto simples e adicione as ferramentas usadas pela equipe:

npm create vite@latest shape-lab
cd shape-lab
npm install
npm install --save-dev eslint @eslint/js globals prettier vitest

Um modelo do Vite fornece ferramentas de desenvolvimento e compilação. Instalar pacotes adicionais não os configura: adicione a configuração do ESLint, crie testes e configure extensões do editor para analisar e formatar ao salvar. Um campo de scripts pode fornecer estas tarefas:

{
  "dev": "vite",
  "build": "vite build",
  "preview": "vite preview",
  "lint": "eslint .",
  "format": "prettier . --write",
  "test": "vitest run"
}

Essas entradas pertencem a "scripts" em package.json. Durante a edição, execute npm run dev; o editor pode analisar e formatar conforme os arquivos mudam. Antes de compartilhar o trabalho, execute npm test. Antes do lançamento, execute npm run build e npm run preview. A pasta dist compilada de um site estático pode então ser enviada a um serviço adequado de hospedagem estática.

Encontre o arquivo que controla uma tarefa

Comece um projeto desconhecido por package.json: seus scripts revelam como o projeto é executado, e suas listas de dependências revelam quais ferramentas esses scripts precisam. Pastas geradas podem ser recriadas; configurações e código-fonte explicam como recriá-las.

Aprenda novas ferramentas uma de cada vez para que um erro ainda tenha uma causa reconhecível. Use a documentação oficial da versão instalada quando comandos ou padrões forem diferentes, pois lançamentos de ferramentas e frameworks mudam com mais frequência do que a sintaxe principal do JavaScript.