package.json "type" & exports

Os campos "type" e "exports" do package.json definem como o Node resolve seu pacote - eles substituem campos main ambíguos e bloqueiam arquivos internos contra importações profundas.

Receita

{
  "name": "@acme/billing-sdk",
  "type": "module",
  "exports": {
    ".": {
      "import": "./dist/index.js",
      "require": "./dist/index.cjs"
    },
    "./package.json": "./package.json"
  },
  "files": ["dist"]
}

Quando usar isso:

• Publicando pacotes internos de monorepo para npm ou Verdaccio
• Bloqueando consumidores de import '@acme/pkg/src/internal/foo.js'
• Bibliotecas CJS/ESM duais durante a transição do ecossistema
• Ferramentas que respeitam exports (TypeScript 5.6+, webpack 5, Node 24)

Exemplo Funcional

{
  "name": "@acme/shared-types",
  "type": "module",
  "exports": {
    ".": "./dist/index.js",
    "./users": "./dist/users.js",
    "./package.json": "./package.json"
  },
  "imports": {
    "#internal/*": "./src/internal/*.js"
  }
}

// consumer.ts
import { UserDto } from '@acme/shared-types/users';

// dentro do pacote @acme/shared-types apenas
import { helper } from '#internal/helper.js';

O que isso demonstra:

• A lista de permissões "exports" é a única superfície importável - caminhos profundos falham sem uma correspondência
• Exportações de subcaminho (./users) publicam pontos de entrada focados sem inchaço de barril
• O campo "imports" mapeia aliases internos (#internal/*) para atalhos privados do pacote
• Exportação explícita "./package.json" quando as ferramentas precisam ler metadados

Mergulho Profundo

Como Funciona

• "type": "module" - Arquivos .js são ESM; use .cjs para CommonJS intencional.
• "exports" - As chaves do objeto são subcaminhos públicos; os valores são arquivos de destino ou objetos condicionais.
• Condições - "import", "require", "node", "default" escolhem variantes por resolvedor.
• Sem correspondência, sem acesso - importar caminhos não exportados lança ERR_PACKAGE_PATH_NOT_EXPORTED.

Formas comuns de exportação

Notas do TypeScript

{
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "import": "./dist/index.js"
    }
  }
}

Combine a condição "types" (ou typesVersions) para que os consumidores recebam tipagens que correspondam à exportação.

Armadilhas

• Apenas definir main sem exports - ferramentas modernas ainda podem permitir importações profundas. Correção: adicione "exports" para encapsular.
• Esquecer .js nos destinos de exportação - deve apontar para arquivos que existem após a compilação. Correção: verificação de CI de que dist corresponde a exports.
• Perigo de pacote duplo - instâncias separadas de import e require quebram instanceof. Correção: prefira apenas ESM para pacotes de aplicativos; documente para bibliotecas.
• Wildcards de exportação muito amplos - "./src/*" expõe internos. Correção: exporte apenas artefatos de dist.
• Protocolo de workspace de monorepo sem compilação - consumidores resolvem para fonte TS incorretamente. Correção: exports aponta para dist compilado em pacotes publicados.

Alternativas

FAQs

Relacionado

• ES Modules (import) - Sintaxe ESM consumindo exports
• Algoritmo de Resolução de Módulos - ordem de resolução
• Interop CJS ↔ ESM - exportações duplas de condição
• Compartilhando Tipos com o Frontend - pacotes de monorepo

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.