TypeScript no AL2023

TypeScript (TS) é uma linguagem de programação baseada em JavaScript (JS) que oferece todos os recursos do JS e também o estende com um sistema de tipos. Em um cenário típico, os programas escritos em TS são traduzidos primeiro para o código JS, depois são executados como qualquer outro programa JS normal pelo Node.js. Na terminologia específica do TS, esse processo de tradução é chamado de “compilação” e é executado por um “compilador”, chamado tsc. O compilador tsc em si é escrito em JS, portanto, para ser executado, ele também precisa de um ambiente de runtime do JS, como Node.js. Ao contrário de alguns outros ambientes de runtime do JS, Node.js só tem suporte experimental e leve ao TS no momento. Um suporte completo ao TS, incluindo verificação de tipos, ainda requer o uso de pacotes de terceiros, como o typescript. A maneira esperada de obter o tsc (compilador do TS) para o ambiente de runtime do Node.js é instalar o módulo de nós typescript. Isso pode ser feito usando um dos gerenciadores de pacotes, normalmente o npm. Há duas formas de instalar o compilador do TS usando npm: globalmente e em um projeto. O método oficialmente recomendado é instalar o compilador do TS por projeto, o que garante consistência e reprodutibilidade a longo prazo para os projetos. No entanto, instalar o compilador do TS globalmente ainda pode ser útil, pois fornece a mesma versão para todo o host e seu runtime do JS e, portanto, para projetos que não têm um compilador do TS instalado localmente. É exatamente assim que os pacotes RPM disponíveis no Amazon Linux, como nodejs20-typescript ou nodejs22-typescript, instalam um compilador do TS: globalmente no nível do sistema e separadamente para cada versão do Node.js compatível.

O tsc não depende diretamente de nenhuma versão do Node.js. O compilador espera determinado nível de recursos de runtime, que são definidos em um arquivo especial (tsconfig.json) por meio de opções como target e lib. Os valores dessas opções representam uma versão do padrão ECMAScript (ES), que pode (ou não) ser compatível com o ambiente de runtime do JS. Versões diferentes do Node.js oferecem suporte a diferentes versões do padrão ES. Quanto mais recente for a versão do Node.js, maior e mais completa será a versão do padrão ES compatível. Se tsconfig.json não existir no diretório-raiz de um projeto, será usado o conjunto padrão de opções de configuração. A tabela de compatibilidade com as diferentes versões do Node.js e os recursos compatíveis de várias versões do padrão ES está disponível em node.green. O tsc tem mais de 100 opções diferentes, que podem ser definidas em tsconfig.json. Também há suporte ao encadeamento de configurações quando algumas opções de configuração são definidas em outro arquivo e, depois, incluídas no arquivo principal. Essa abordagem permite instalar uma configuração básica do TS compatível com determinada versão do Node.js, depois estendê-lo com opções específicas do projeto. Felizmente, as configurações básicas do TS para o Node.js estão disponíveis na forma de módulos de nós que podem ser instalados em uma pasta de projeto usando npm. Aqui está o código-fonte da configuração para o Node.js versão 18, 20 e 22.

O design de runtime baseado em Node.js tem certa fraqueza: ele só oferece suporte a uma versão do runtime em um host e requer reprodutibilidade e consistência de todas as dependências no nível do projeto. Isso levou à seguinte abordagem comum de uso do TypeScript: a instalação local, dentro de um projeto, do compilador do TS, da configuração básica do TS para a versão do Node.js atual e de todas as dependências de software. Embora se espere que os módulos de nós instalados globalmente sejam apenas ferramentas de CLI, como npm, o tsc, que também é uma ferramenta de CLI, raramente é instalado globalmente. Felizmente, as instalações globais (em todo o sistema) e locais (dentro de um projeto) do tsc podem coexistir sem problemas e também podem ser versões diferentes que são usadas de forma independente. Observe que um tsc instalado localmente deve ser executado usando a ferramenta npx, que é instalada com o npm. Assim, mesmo com um compilador do TS do sistema, os usuários têm a oportunidade de escolher versões dos componentes do runtime, como Node.js (alternando a versão ativa por meio da ferramenta alternatives), um compilador do TS (instalando-o local ou globalmente, e também alternando a versão ativa por meio da ferramenta alternatives), e configurar para as necessidades específicas.

O Amazon Linux empacota um compilador do TS da mesma forma que outros módulos de nós instalados globalmente, como npm, com base na versão do Node.js. Pacotes e binários têm namespace e contêm a versão principal do Node.js como parte de seus nomes. O nome do executável padrão do compilador, tsc, é gerenciado no runtime pela ferramenta alternatives e aponta para a versão atualmente ativa do Node.js para a qual ele foi instalado e será executado. Essa seleção não depende da versão atual do runtime do Node.js. É possível ter o executável node apontando para o Node.js 20 e o tsc configurado para ser interpretado pelo Node.js 22. Também é possível usar os nomes com namespace de um compilador do TS, por exemplo, tsc-{MAJOR_VERSION}, independentemente do nome tsc padrão configurado.

Um exemplo de instalação e uso de várias versões do Node e de um compilador do TS no mesmo sistema:

# Check the AL2023 release
$ cat /etc/amazon-linux-release
Amazon Linux release 2023.9.20250929 (Amazon Linux)

# Install a TypeScript compiler for Node.js 20 and 22
# Node.js 20 and 22 will be installed automatically
$ sudo dnf install -qy nodejs20-typescript nodejs22-typescript

# Check what was installed
$ rpm -q nodejs20 nodejs20-typescript nodejs22 nodejs22-typescript
nodejs20-20.19.5-1.amzn2023.0.1.x86_64
nodejs20-typescript-5.9.2-1.amzn2023.0.1.noarch
nodejs22-22.19.0-1.amzn2023.0.1.x86_64
nodejs22-typescript-5.9.2-1.amzn2023.0.1.noarch

# Check the active version of Node.js - it is version 20
$ alternatives --display node
node - status is auto.
 link currently points to /usr/bin/node-20
/usr/bin/node-20 - priority 100
 slave npmrc: /usr/lib/nodejs20/lib/node_modules/npm/npmrc
 slave npm: /usr/bin/npm-20
 slave npx: /usr/bin/npx-20
 slave node_modules: /usr/lib/nodejs20/lib/node_modules
/usr/bin/node-22 - priority 100
 slave npmrc: /usr/lib/nodejs22/lib/node_modules/npm/npmrc
 slave npm: /usr/bin/npm-22
 slave npx: /usr/bin/npx-22
 slave node_modules: /usr/lib/nodejs22/lib/node_modules
Current 'best' version is /usr/bin/node-20.

# Check the active JS runtime version for TypeScript
# Currently, the tsc compiler will be executed by Node.js 22
$ alternatives --display tsc
tsc - status is auto.
 link currently points to /usr/bin/tsc-22
/usr/bin/tsc-22 - priority 100
 slave tsserver: /usr/bin/tsserver-22
/usr/bin/tsc-20 - priority 100
 slave tsserver: /usr/bin/tsserver-20
Current 'best' version is /usr/bin/tsc-22.

# Check versions printed by executables
$ node -v
v20.19.5

$ tsc -v
Version 5.9.2

# while the node is 20, tsc is executed by node 22 anyway
$ head -1 /usr/bin/tsc
#!/usr/bin/node-22

# However, instead of default executable names, e.g. node or tsc,
# we can use namespaced names to target any installed version
$ node-20 -v
v20.19.5

$ node-22 -v
v22.19.0

$ tsc-20 -v
Version 5.9.2

$ tsc-22 -v
Version 5.9.2

$ head -1 /usr/bin/tsc-20
#!/usr/bin/node-20

$ head -1 /usr/bin/tsc-22
#!/usr/bin/node-22