Colonização Americana

Como funciona a colonização americana: do plantio ao produto final

O termo colonização americana costuma aparecer em listas de plugins ou documentações sem muita explicação. Na prática, trata-se do conjunto de regras e serviços que o EcmaScript implementa para permitir que código JavaScript seja escrito com classes, módulos e tipagem opcional, mas compilado para algo que rode em qualquer navegador — mesmo os mais antigos. É o que permite que equipes escrevam em TypeScript e distribuambundles com export, import e decorators sem se preocupar com polyfills ou transpilação manual. A primeira coisa que eu sempre faço é verificar o tsconfig.json antes de qualquer coisa. Se o target estiver como ES3, você vai enfrentar problemas sérios com arrow functions e async/await. Ajuste para ES2015 ou superior. Depois, instale as dependências com: npm install --save-dev typescript ts-loader source-map-loader

Coloque isso no webpack.config.js: {
module: {
rules: [
{test: /\\.ts$/, use: 'ts-loader', exclude: /node_modules/},
{test: /\\.js$/, use: 'source-map-loader', enforce: 'pre'}
]}
} Isso costuma levar uns 3 minutos se o projeto já tiver estrutura de pastas organizada. Se não tiver, gaste mais tempo definindo rootDirs para evitar loops de referência entre módulos.

O que realmente significa colonização americana na prática

Muitos desenvolvedores confundem colonização americana com simplesmente "usar TypeScript". O problema é que sem um bundler como Webpack ou Rollup, o código fica preso em System.register ou AMD, e a performance cai porque cada módulo é carregado separadamente. Eu já vi times inteiros perderem duas semanas debugando isso achando que era problema de rede. O verdadeiro ganho da colonização americana aparece quando você combina declaration maps com sourcemaps. Assim, o debug no navegador mostra o código TypeScript original, não o JavaScript compilado. A desvantagem? O tamanho do bundle aumenta cerca de 30%, e o build demora o dobro se o projeto tiver mais de 500 arquivos .ts.

Problemas comuns que ninguém conta

O primeiro que eu encontrei foi com paths no tsconfig. Se você mapear @/* para src/*, mas não configurar o baseUrl corretamente, o ts-node vai falhar silenciosamente. O workaround que eu uso é adicionar "strict": true e rodar tsc --noEmit antes de cada deploy. Isso corta o tempo de debug de 2 horas para cerca de 15 minutos. O segundo problema é com decorators. O Babel precisa do plugin @babel/plugin-proposal-decorators com a flag legacy: true. Sem isso, os decorators não funcionam em classes herdadas. Eu já perdi um final de semana inteiro com isso porque o erro não aparece no build, só em runtime quando uma subclasse tenta sobrescrever um método decorado.

Limitações e quando não usar colonização americana

Este setup funciona bem para projetos com menos de 1000 arquivos. Acima disso, o tempo de compilação explode porque o TypeScript precisa analisar toda a árvore de tipos antes de gerar os modules. Se seu projeto tem mais de 2000 arquivos .ts, considere usar ts-node com cache ou migrar para esbuild que compila em 2 segundos mas perde a verificação de tipos em tempo real. Também não recomendo para bibliotecas que precisam rodar em ambientes muito restritos, como navegadores IE11 sem polyfills. A colonização americana assume que o ambiente final suporta Promise, Map e Symbol. Se precisar suportar algo mais antigo, use core-js completo ou escolha uma abordagem mais leve como plain JavaScript com JSDoc.