Noções Básicas de Node.js

10 exemplos para você começar com Fundamentos de Node.js - 7 básicos e 3 intermediários.

Pré-requisitos

• Instale o Node.js 24.18.0 (Active LTS) via fnm, nvm ou Volta.
• Verifique com node --version e npm --version (npm 10+ vem com Node 24).
• Novos projetos devem usar "type": "module" em package.json para ESM por padrão.

Exemplos Básicos

1. Verifique Sua Versão do Node

Confirme o runtime antes de executar qualquer script ou implantar.

console.log(process.version);       // v24.18.0
console.log(process.versions.v8);   // Versão do motor V8
console.log(process.versions.uv);   // Versão do libuv

• process.version é a string autoritativa do runtime - registre-a na inicialização em produção.
• process.versions expõe V8, libuv, OpenSSL e outros bindings nativos.
• CI e imagens Docker devem corresponder à versão fixada em package.json engines.

Relacionado: Instalação e Gerenciamento de Versão - fixe o LTS entre equipes | Política de Lançamento e LTS do Node.js - o que a produção pode executar

2. Execute um Script com node

A maneira mais simples de executar um arquivo JavaScript compilado de TypeScript ou JavaScript puro.

// hello.mjs
console.log('Olá do Node.js', process.version);

node hello.mjs

• Salve como .mjs ou defina "type": "module" em package.json para sintaxe ESM.
• node file.ts funciona com tsx em desenvolvimento; a produção compila com tsc primeiro.
• O código de saída 0 significa sucesso; não zero sinaliza falha para shells e CI.

Relacionado: Executando Scripts e Shebang - torne os scripts executáveis

3. Use fetch Integrado

Node 18+ inclui um fetch global - nenhum pacote node-fetch é necessário.

const response = await fetch('https://nodejs.org/dist/index.json');
const releases = await response.json() as Array<{ version: string; lts: string | false }>;
const lts = releases.find((r) => r.lts !== false);
console.log('Tag LTS atual:', lts?.lts, lts?.version);

• fetch retorna objetos Response padrão da Web - mesma API que navegadores.
• Sempre verifique response.ok ou response.status antes de analisar o corpo.
• Para baixar arquivos grandes em streaming, use response.body como um Web ReadableStream.

Relacionado: Como o Node.js Funciona - onde I/O é executado fora da thread principal

4. Leia Variáveis de Ambiente

A configuração pertence ao ambiente, não codificada em fonte.

const port = Number(process.env.PORT ?? 3000);
const nodeEnv = process.env.NODE_ENV ?? 'development';
 
console.log(`Iniciando na porta ${port} em modo ${nodeEnv}`);

• process.env é um objeto simples de valores de string - converta tipos explicitamente.
• Use ?? para padrões; string vazia "" é truthy e não passará por ||.
• Valide as variáveis necessárias na inicialização com Zod ou uma biblioteca de esquema antes de aceitar tráfego.

5. Importe um Módulo ES

ESM é o caminho a seguir - use import estático no topo dos arquivos.

import { readFile } from 'node:fs/promises';
import { fileURLToPath } from 'node:url';
import path from 'node:path';
 
const __filename = fileURLToPath(import.meta.url);
const __dirname = path.dirname(__filename);
 
const pkg = await readFile(path.join(__dirname, 'package.json'), 'utf8');
console.log(JSON.parse(pkg).name);

• Prefira imports integrados com node: para clareza e compatibilidade futura.
• import.meta.url substitui __filename e __dirname do CJS.
• await de nível superior é permitido em módulos ESM no escopo do módulo.

Relacionado: Como o Node.js Funciona - V8 e o carregador de módulos

6. Manipule Erros com try/catch

Erros assíncronos em expressões await se propagam como throws síncronos.

async function loadConfig(): Promise<Record<string, string>> {
  try {
    const res = await fetch(process.env.CONFIG_URL!);
    if (!res.ok) throw new Error(`HTTP ${res.status}`);
    return await res.json() as Record<string, string>;
  } catch (err) {
    console.error('Falha ao carregar configuração:', err);
    throw err; // relance para que o processo saia ou um supervisor reinicie
  }
}

• Rejeições de promessa não tratadas podem travar o Node em produção - sempre anexe .catch() ou use try/catch.
• Registre o erro com contexto (URL, status) antes de relançar.
• Para servidores HTTP, mapeie erros para respostas JSON estruturadas em vez de traces de pilha.

7. Experimento Rápido na REPL

Prototipe APIs interativamente sem criar um arquivo.

node

> await fetch('https://httpbin.org/get').then(r => r.json())
> Object.keys(process.versions)
> .exit

• A REPL suporta await de nível superior quando iniciada com node (nenhuma flag -e necessária no Node 24).
• Use .save nome_arquivo para persistir uma sessão e .load nome_arquivo para reproduzi-la.
• O autocompletar com Tab e .help listam todos os comandos de ponto.

Relacionado: A REPL e Experimentos Rápidos - fluxos de trabalho REPL mais aprofundados

Exemplos Intermediários

8. Escreva um Servidor HTTP Mínimo

node:http é integrado - nenhum framework é necessário para verificações de integridade e sondas.

import { createServer } from 'node:http';
 
const server = createServer((req, res) => {
  if (req.url === '/health') {
    res.writeHead(200, { 'content-type': 'application/json' });
    res.end(JSON.stringify({ status: 'ok', version: process.version }));
    return;
  }
  res.writeHead(404).end();
});
 
server.listen(3000, () => console.log('Ouvindo em :3000'));

• O callback createServer é executado em cada requisição - mantenha-o não bloqueante.
• Defina content-type explicitamente; caso contrário, os clientes assumem text/plain.
• Para APIs de produção, passe para Express 5 ou Fastify 5 para roteamento e validação.

9. Execute Testes com node:test

O executor de testes integrado do Node não precisa de instalação do Jest para testes unitários.

// math.test.ts
import { test, describe } from 'node:test';
import assert from 'node:assert/strict';
 
function add(a: number, b: number): number {
  return a + b;
}
 
describe('add', () => {
  test('soma dois números', () => {
    assert.equal(add(2, 3), 5);
  });
});

node --import tsx --test math.test.ts

• node:test suporta describe, hooks e testes assíncronos nativamente.
• Use node:assert/strict para verificações de igualdade estrita.
• Combine com tsx em desenvolvimento para TypeScript; compile antes da CI se preferir a saída do tsc.

10. Saída Graciosa do Processo

Ouça sinais para que contêineres e orquestradores possam drenar o trabalho de forma limpa.

let shuttingDown = false;
 
function shutdown(signal: string): void {
  if (shuttingDown) return;
  shuttingDown = true;
  console.log(`Recebido ${signal}, drenando...`);
  setTimeout(() => process.exit(0), 2000);
}
 
process.on('SIGTERM', () => shutdown('SIGTERM'));
process.on('SIGINT', () => shutdown('SIGINT'));

• O Kubernetes envia SIGTERM antes de matar um pod - você tem cerca de 30 segundos para drenar.
• Feche pools de banco de dados e servidores HTTP antes de chamar process.exit.
• Manipuladores de desligamento idempotentes evitam bugs de fechamento duplo em sinais repetidos.

Relacionado: Como o Node.js Funciona - modelo de thread única e tratamento de sinais

Versões da Stack: Esta página foi escrita para Node.js 24.18.0 (Active LTS), npm 10+, TypeScript 5.6+, Express 5, Fastify 5 e NestJS 11.