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:
tsTryexport {};
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:
tsTry// @filename: hello.tsexport default functionhelloWorld () {console .log ("Hello, world!");}
Ela é então importada com:
tsTryimporthelloWorld from "./hello.js";helloWorld ();
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:
tsTry// @filename: maths.tsexport varpi = 3.14;export letsquareTwo = 1.41;export constphi = 1.61;export classRandomNumberGenerator {}export functionabsolute (num : number) {if (num < 0) returnnum * -1;returnnum ;}
Elas podem ser usadas em outro arquivo pela sintaxe import:
tsTryimport {pi ,phi ,absolute } from "./maths.js";console .log (pi );constabsPhi =absolute (phi );
Sintaxe de import adicional
Um import pode ser renomeado usando um formato como import {antigo as novo}:
tsTryimport {pi asπ } from "./maths.js";console .log (π );
Você pode misturar a sintaxe acima em um único import:
tsTry// @filename: maths.tsexport constpi = 3.14;export default classRandomNumberGenerator {}// @filename: app.tsimportRandomNumberGenerator , {pi asπ } from "./maths.js";RandomNumberGenerator ;console .log (π );
Você pode pegar todos os objetos exportados e colocá-los em um único namespace usando * as nome:
tsTry// @filename: app.tsimport * asmath from "./maths.js";console .log (math .pi );constpositivePhi =math .absolute (math .phi );
Você pode importar um arquivo e não incluir nenhuma variável no módulo atual usando import "./file":
tsTry// @filename: app.tsimport "./maths.js";console .log ("3.14");
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:
tsTry// @filename: animal.tsexport typeCat = {breed : string;yearOfBirth : number };export interfaceDog {breeds : string[];yearOfBirth : number;}// @filename: app.tsimport {Cat ,Dog } from "./animal.js";typeAnimals =Cat |Dog ;
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:
tsTry// @filename: animal.tsexport typeCat = {breed : string;yearOfBirth : number };export typeDog = {breeds : string[];yearOfBirth : number };export constcreateCatName = () => "fluffy";// @filename: valid.tsimport type {Cat ,Dog } from "./animal.js";export typeAnimals =Cat |Dog ;// @filename: app.tsimport type {createCatName } from "./animal.js";const'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'.name =(); createCatName
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:
tsTry// @filename: app.tsimport {createCatName , typeCat , typeDog } from "./animal.js";export typeAnimals =Cat |Dog ;constname =createCatName ();
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:
tsTryimportfs = require("fs");constcode =fs .readFileSync ("hello.ts", "utf8");
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.
tsTryfunctionabsolute (num : number) {if (num < 0) returnnum * -1;returnnum ;}module .exports = {pi : 3.14,squareTwo : 1.41,phi : 1.61,absolute ,};
Depois, esses arquivos podem ser importados por uma instrução require:
tsTryconstmaths =require ("./maths");maths .pi ;
Ou você pode simplificar um pouco usando o recurso de desestruturação do JavaScript:
tsTryconst {squareTwo } =require ("./maths");squareTwo ;
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 intactosmodule, 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:
tsTryimport {valueOfPi } from "./constants.js";export consttwoPi =valueOfPi * 2;
ES2020
tsTryimport { valueOfPi } from "./constants.js";export const twoPi = valueOfPi * 2;
CommonJS
tsTry"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;
UMD
tsTry(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;});
Observe que ES2020 é, na prática, o mesmo que o
index.tsoriginal.
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.