Módulos

O JavaScript tem um longo histórico de formas diferentes de modularizar código. O TypeScript existe desde 2012 e implementou suporte a muitos desses formatos, mas, com o tempo, a comunidade e a especificação do JavaScript convergiram para um formato chamado ES Modules (ou módulos ES6). Você pode conhecê-lo pela sintaxe import/export.

ES Modules foi adicionado à especificação do JavaScript em 2015, e, em 2020, já tinha amplo suporte na maioria dos navegadores e runtimes JavaScript.

Para manter o foco, o handbook vai cobrir tanto ES Modules quanto a sintaxe module.exports = do seu antecessor CommonJS, popular até hoje. Você pode encontrar informações sobre os outros padrões de módulo na seção de referência, em Módulos.

Como os módulos JavaScript são definidos

No TypeScript, assim como no ECMAScript 2015, qualquer arquivo que contenha um import ou export no nível superior é considerado um módulo.

Por outro lado, um arquivo sem nenhuma declaração import ou export no nível superior é tratado como um script, cujo conteúdo fica disponível no escopo global (e, portanto, também para os módulos).

Os módulos são executados dentro do próprio escopo, e não no escopo global. Isso significa que variáveis, funções, classes etc. declaradas em um módulo não são visíveis fora dele, a menos que sejam explicitamente exportadas por uma das formas de export. Da mesma forma, para consumir uma variável, função, classe, interface etc. exportada por outro módulo, ela precisa ser importada por uma das formas de import.

Não módulos

Antes de começar, é importante entender o que o TypeScript considera um módulo. A especificação do JavaScript determina que qualquer arquivo JavaScript sem uma declaração import, export ou await de nível superior deve ser considerado um script, e não um módulo.

Dentro de um arquivo de script, variáveis e tipos são declarados no escopo global compartilhado, e presume-se que você vai usar a opção de compilador outFile para juntar vários arquivos de entrada em um único arquivo de saída, ou usar várias tags <script> no seu HTML para carregar esses arquivos (na ordem correta!).

Se você tem um arquivo que não tem nenhum import ou export no momento, mas quer que ele seja tratado como módulo, adicione a linha:

ts
export {};
Try

que transforma o arquivo em um módulo que não exporta nada. Essa sintaxe funciona independentemente do seu alvo de módulo.

Módulos no TypeScript

Leitura complementar:
Impatient JS (Modules)
MDN: JavaScript Modules

Há três pontos principais a considerar ao escrever código baseado em módulos no TypeScript:

  • Sintaxe: Qual sintaxe quero usar para importar e exportar coisas?
  • Resolução de módulos: Qual é a relação entre os nomes (ou caminhos) dos módulos e os arquivos no disco?
  • Alvo de saída do módulo: Como deve ser o módulo JavaScript emitido?

Sintaxe de ES Module

Um arquivo pode declarar uma exportação principal via export default:

ts
// @filename: hello.ts
export default function helloWorld() {
console.log("Hello, world!");
}
Try

Ela é então importada com:

ts
import helloWorld from "./hello.js";
helloWorld();
Try

Além da exportação padrão, você pode ter mais de uma exportação de variáveis e funções usando export sem o default:

ts
// @filename: maths.ts
export var pi = 3.14;
export let squareTwo = 1.41;
export const phi = 1.61;
 
export class RandomNumberGenerator {}
 
export function absolute(num: number) {
if (num < 0) return num * -1;
return num;
}
Try

Elas podem ser usadas em outro arquivo pela sintaxe import:

ts
import { pi, phi, absolute } from "./maths.js";
 
console.log(pi);
const absPhi = absolute(phi);
const absPhi: number
Try

Sintaxe de import adicional

Um import pode ser renomeado usando um formato como import {antigo as novo}:

ts
import { pi as π } from "./maths.js";
 
console.log(π);
(alias) var π: number import π
Try

Você pode misturar a sintaxe acima em um único import:

ts
// @filename: maths.ts
export const pi = 3.14;
export default class RandomNumberGenerator {}
 
// @filename: app.ts
import RandomNumberGenerator, { pi as π } from "./maths.js";
 
RandomNumberGenerator;
(alias) class RandomNumberGenerator import RandomNumberGenerator
 
console.log(π);
(alias) const π: 3.14 import π
Try

Você pode pegar todos os objetos exportados e colocá-los em um único namespace usando * as nome:

ts
// @filename: app.ts
import * as math from "./maths.js";
 
console.log(math.pi);
const positivePhi = math.absolute(math.phi);
const positivePhi: number
Try

Você pode importar um arquivo e não incluir nenhuma variável no módulo atual usando import "./file":

ts
// @filename: app.ts
import "./maths.js";
 
console.log("3.14");
Try

Nesse caso, o import não faz nada. No entanto, todo o código de maths.ts foi avaliado, o que pode disparar efeitos colaterais que afetam outros objetos.

Sintaxe de ES Module específica do TypeScript

Tipos podem ser exportados e importados com a mesma sintaxe usada para valores JavaScript:

ts
// @filename: animal.ts
export type Cat = { breed: string; yearOfBirth: number };
 
export interface Dog {
breeds: string[];
yearOfBirth: number;
}
 
// @filename: app.ts
import { Cat, Dog } from "./animal.js";
type Animals = Cat | Dog;
Try

O TypeScript estendeu a sintaxe de import com dois conceitos para declarar a importação de um tipo:

import type

É uma instrução de import que só pode importar tipos:

ts
// @filename: animal.ts
export type Cat = { breed: string; yearOfBirth: number };
export type Dog = { breeds: string[]; yearOfBirth: number };
export const createCatName = () => "fluffy";
 
// @filename: valid.ts
import type { Cat, Dog } from "./animal.js";
export type Animals = Cat | Dog;
 
// @filename: app.ts
import type { createCatName } from "./animal.js";
const name = createCatName();
'createCatName' cannot be used as a value because it was imported using 'import type'.1361'createCatName' cannot be used as a value because it was imported using 'import type'.
Try
Imports type em linha

A partir do TypeScript 4.5, também é possível prefixar imports individuais com type, para indicar que a referência importada é um tipo:

ts
// @filename: app.ts
import { createCatName, type Cat, type Dog } from "./animal.js";
 
export type Animals = Cat | Dog;
const name = createCatName();
Try

Juntas, essas formas permitem que um transpilador que não é do TypeScript, como Babel, swc ou esbuild, saiba quais imports podem ser removidos com segurança.

Sintaxe de ES Module com comportamento CommonJS

O TypeScript tem uma sintaxe de ES Module que se relaciona diretamente com o require do CommonJS e do AMD. Os imports com ES Module são, na maioria dos casos, iguais ao require desses ambientes, mas essa sintaxe garante uma correspondência 1 para 1, no seu arquivo TypeScript, com a saída CommonJS:

ts
import fs = require("fs");
const code = fs.readFileSync("hello.ts", "utf8");
Try

Você pode saber mais sobre essa sintaxe na página de referência de módulos.

Sintaxe CommonJS

CommonJS é o formato em que a maioria dos módulos do npm é distribuída. Mesmo que você escreva usando a sintaxe de ES Modules acima, ter uma noção básica de como funciona a sintaxe CommonJS vai ajudar você a depurar com mais facilidade.

Exportando

Identificadores são exportados definindo a propriedade exports de uma variável global chamada module.

ts
function absolute(num: number) {
if (num < 0) return num * -1;
return num;
}
 
module.exports = {
pi: 3.14,
squareTwo: 1.41,
phi: 1.61,
absolute,
};
Try

Depois, esses arquivos podem ser importados por uma instrução require:

ts
const maths = require("./maths");
maths.pi;
any
Try

Ou você pode simplificar um pouco usando o recurso de desestruturação do JavaScript:

ts
const { squareTwo } = require("./maths");
squareTwo;
const squareTwo: any
Try

Interoperabilidade entre CommonJS e ES Modules

Há uma incompatibilidade de recursos entre CommonJS e ES Modules quanto à distinção entre um import padrão (default) e um import do objeto de namespace do módulo. O TypeScript tem uma flag do compilador para reduzir o atrito entre os dois conjuntos diferentes de restrições: esModuleInterop.

Opções de resolução de módulos do TypeScript

Resolução de módulos é o processo de pegar uma string da instrução import ou require e determinar a qual arquivo essa string se refere.

O TypeScript inclui duas estratégias de resolução: Classic e Node. A Classic, que é o padrão quando a opção do compilador module não é commonjs, é incluída por compatibilidade com versões anteriores. A estratégia Node replica o funcionamento do Node.js no modo CommonJS, com verificações adicionais para .ts e .d.ts.

Há muitas flags do TSConfig que influenciam a estratégia de módulos no TypeScript: moduleResolution, baseUrl, paths, rootDirs.

Para todos os detalhes sobre como essas estratégias funcionam, consulte a página de referência Resolução de módulos.

Opções de saída de módulos do TypeScript

Há duas opções que afetam a saída JavaScript emitida:

  • target, que determina quais recursos do JS são rebaixados (convertidos para rodar em runtimes JavaScript mais antigos) e quais são mantidos intactos
  • module, que determina qual código é usado para que os módulos interajam entre si

O target que você usa é determinado pelos recursos disponíveis no runtime JavaScript em que você espera executar o código TypeScript. Pode ser: o navegador web mais antigo que você suporta, a versão mais baixa do Node.js em que você espera rodar ou restrições específicas do seu runtime, como o Electron, por exemplo.

Toda comunicação entre módulos acontece por meio de um carregador de módulos; a opção do compilador module determina qual deles é usado. Em tempo de execução, o carregador de módulos é responsável por localizar e executar todas as dependências de um módulo antes de executá-lo.

Por exemplo, aqui está um arquivo TypeScript que usa a sintaxe de ES Modules, mostrando algumas opções diferentes para module:

ts
import { valueOfPi } from "./constants.js";
 
export const twoPi = valueOfPi * 2;
Try

ES2020

ts
import { valueOfPi } from "./constants.js";
export const twoPi = valueOfPi * 2;
 
Try

CommonJS

ts
"use strict";
Object.defineProperty(exports, "__esModule", { value: true });
exports.twoPi = void 0;
const constants_js_1 = require("./constants.js");
exports.twoPi = constants_js_1.valueOfPi * 2;
 
Try

UMD

ts
(function (factory) {
if (typeof module === "object" && typeof module.exports === "object") {
var v = factory(require, exports);
if (v !== undefined) module.exports = v;
}
else if (typeof define === "function" && define.amd) {
define(["require", "exports", "./constants.js"], factory);
}
})(function (require, exports) {
"use strict";
Object.defineProperty(exports, "__esModule", { value: true });
exports.twoPi = void 0;
const constants_js_1 = require("./constants.js");
exports.twoPi = constants_js_1.valueOfPi * 2;
});
 
Try

Observe que ES2020 é, na prática, o mesmo que o index.ts original.

Você pode ver todas as opções disponíveis e como fica o código JavaScript emitido para cada uma na Referência do TSConfig para module.

Namespaces do TypeScript

O TypeScript tem seu próprio formato de módulo chamado namespaces, que é anterior ao padrão ES Modules. Essa sintaxe tem muitos recursos úteis para criar arquivos de definição complexos, e ainda é bastante usada no DefinitelyTyped. Embora não esteja descontinuada, a maioria dos recursos de namespaces existe em ES Modules, e recomendamos usar ES Modules para se alinhar à direção do JavaScript. Você pode saber mais sobre namespaces na página de referência de namespaces.

The TypeScript docs are an open source project. Help us improve these pages by sending a Pull Request ❤

Contributors to this page:
RCRyan Cavanaugh  (52)
OTOrta Therox  (7)
MMyo  (3)
ABAndrew Branch  (2)
HAHossein Ahmadian-Yazdi  (2)
20+

Last updated: Nov 16, 2026