Como corrigir erro de módulo não encontrado em Node.js e TypeScript

O erroErro: Não é possível encontrar o módulo ‘x’ (ouNão é possível encontrar o módulo ‘x’ ou suas declarações de tipo correspondentesno TypeScript) é extremamente comum. Tem várias causas distintas – veja como diagnosticar e corrigir cada uma.

Causa 1: Pacote não instalado

# The most common cause — you forgot to install it
npm install express

# Reinstall everything if node_modules is corrupted
rm -rf node_modules package-lock.json
npm install

# Verify it's actually in package.json
npm list express

Causa 2: Caminho de importação errado (importações relativas)

// 🐛 Wrong path
import { helper } from './utils/helper';  // but file is at ./lib/helper

// ✅ Fix: correct the relative path
import { helper } from './lib/helper';

// Common mistakes:
// - Missing ./ for local files: import x from 'utils' looks in node_modules
// - Wrong case: ./Helper vs ./helper (case-sensitive on Linux!)
// - Missing file extension in ESM (see Cause 5)

Causa 3: Declarações de tipo ausentes (TypeScript)

# Error: Cannot find module 'lodash' or its corresponding type declarations

# The package works but has no bundled types. Install @types:
npm install --save-dev @types/lodash

# For packages that will never have types, declare them:
# create src/types/untyped-module.d.ts
declare module 'some-untyped-package';

Causa 4: Aliases de caminho tsconfig não configurados

// You use import { x } from '@/utils' but it's not configured

// tsconfig.json — add path mapping
{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"]
    }
  }
}

// For runtime (Node), you also need tsconfig-paths or a bundler:
// npm install -D tsconfig-paths
// node -r tsconfig-paths/register dist/index.js
// Or use tsx which handles this automatically

Causa 5: Problemas de extensão ESM vs CommonJS

// In ESM ("type": "module" in package.json), you MUST include .js extension
// even when importing .ts files:

// 🐛 Fails in ESM
import { helper } from './utils/helper';

// ✅ Correct in ESM
import { helper } from './utils/helper.js';  // yes, .js even for .ts source

// package.json
{
  "type": "module"
}

// tsconfig.json
{
  "compilerOptions": {
    "module": "ESNext",
    "moduleResolution": "bundler"  // or "nodenext"
  }
}

Causa 6: Módulo instalado, mas não construído (Monorepo/Workspace)

# In a monorepo, the dependency package hasn't been built yet
# Cannot find module '@myorg/shared'

# Build the dependency first
npm run build --workspace=@myorg/shared

# Or build all packages (Turborepo/Nx)
turbo build
npx nx run-many --target=build

Lista de verificação de diagnóstico

1. Está instalado? Correnpm list <module>
2. O caminho está correto? Verifique a distinção entre maiúsculas e minúsculas e o caminho relativo
3. Precisa de @types? Experimentenpm i -D @types/<module>
4. Questão do ESM? Adicionar.js extensões se"type": "module"
5. Alias do caminho? Verifique tsconfigpaths e resolvedor de tempo de execução
6. Reinicie o servidor TS no seu editor (Código VS: Cmd+Shift+P, depois “Reiniciar Servidor TS”)

Resolução do Módulo do Node — Como Funciona

// import 'foo' (no ./) → Node looks in:
//   1. Core modules (fs, path, http)
//   2. node_modules in current dir
//   3. node_modules in parent dirs, up to root

// import './foo' (with ./) → resolves relative to current file
//   Looks for: ./foo.js, ./foo.json, ./foo/index.js, etc.

// Understanding this explains most "cannot find module" errors:
// - No ./ means Node searches node_modules (fails if it's a local file)
// - ./ means relative path (fails if the path is wrong)

Perguntas Frequentes

P: Por que funciona localmente, mas falha no servidor/CI?
R: Geralmente diferencia maiúsculas de minúsculas – macOS/Windows não diferenciam maiúsculas de minúsculas, o Linux não. ./Helper funciona localmente, mas falha no Linux se o arquivo for./helper. Sempre corresponda ao caso exato.

P: Instalei o pacote, mas ainda recebo o erro. Por que?
R: Reinicie o servidor TypeScript do seu editor ou o servidor de desenvolvimento. Verifique também se o pacote está emdependencies, não apenas instalado localmente sem salvar. Exclua node_modules e reinstale se não tiver certeza.

P: Qual é a diferença entre o erro do módulo e o erro de declaração de tipo?
R: “Não é possível encontrar o módulo” sozinho = o módulo JS não foi encontrado. “…ou suas declarações de tipo correspondentes” = o módulo existe, mas o TypeScript não consegue encontrar tipos. A segunda precisa@types/x ou um.d.ts declaração.

P: Como faço para corrigir isso em uma versão do Docker?
R: Certifique-senpm install é executado dentro do contêiner (não copie o host node_modules). Copie package.json primeiro, instale e depois copie o código-fonte – isso também melhora o cache da camada Docker.

P: Devo usar “moduleResolution”: “node” ou “bundler”?
R: Em 2026, use"bundler" para projetos construídos com Vite/esbuild/webpack (nenhuma extensão necessária), ou"nodenext" para Node ESM puro (extensões necessárias). Evite o legado"node" para novos projetos.

Conclusão

“Não é possível encontrar o módulo” quase sempre se resume a um dos seguintes: o pacote não está instalado, o caminho de importação está errado (verifique o caso!), faltando@types, requisitos de extensão do ESM ou aliases de caminho não configurados. Analise a lista de verificação de diagnóstico de cima para baixo —npm list, verifique o caminho, verifique@typese reinicie seu servidor TS. Noventa por cento dos casos são resolvidos nas três primeiras etapas.