Projetos TypeScript

O gerador de projetos TypeScript pode ser usado para criar bibliotecas ou aplicações modernas em TypeScript configuradas com melhores práticas como Módulos ECMAScript (ESM), referências de projeto TypeScript, Vitest para execução de testes e ESLint para análise estática.

Uso

Gerar um Projeto TypeScript

Você pode gerar um novo projeto TypeScript de duas formas:

VSCode

1. Instale o Nx Console VSCode Plugin se ainda não o fez
2. Abra o console Nx no VSCode
3. Clique em Generate (UI) na seção "Common Nx Commands"
4. Procure por @aws/nx-plugin - ts#project
5. Preencha os parâmetros obrigatórios
6. Clique em Generate

CLI

pnpm

pnpm nx g @aws/nx-plugin:ts#project

yarn

yarn nx g @aws/nx-plugin:ts#project

npm

npx nx g @aws/nx-plugin:ts#project

bun

bunx nx g @aws/nx-plugin:ts#project

Você também pode realizar uma execução simulada para ver quais arquivos seriam alterados

pnpm

pnpm nx g @aws/nx-plugin:ts#project --dry-run

yarn

yarn nx g @aws/nx-plugin:ts#project --dry-run

npm

npx nx g @aws/nx-plugin:ts#project --dry-run

bun

bunx nx g @aws/nx-plugin:ts#project --dry-run

Opções

Parâmetro	Tipo	Padrão	Descrição
name Obrigatório	string	-	Library name.
directory	string	packages	Parent directory where the library is placed.
subDirectory	string	-	The sub directory the lib is placed in. By default this is the library name.

Saída do Gerador

O gerador criará a seguinte estrutura de projeto no diretório <directory>/<name>:

• Directorysrc Código-fonte TypeScript

  • index.ts
• project.json Configuração do projeto e targets de build
• tsconfig.json Configuração base TypeScript para este projeto (estende o tsconfig.base.json raiz do workspace)
• tsconfig.lib.json Configuração TypeScript para sua biblioteca (código de runtime ou empacotado)
• tsconfig.spec.json Configuração TypeScript para seus testes
• vite.config.ts Configuração para o Vitest
• eslint.config.mjs Configuração para o ESLint

Dica

Observe que nenhum arquivo package.json é criado para este projeto! Você pode entender o motivo abaixo.

Você também notará alterações nos seguintes arquivos na raiz do workspace:

• nx.json A configuração do Nx é atualizada para configurar o plugin @nx/js/typescript para seu projeto
• tsconfig.base.json Um alias TypeScript é configurado para seu projeto para permitir importação por outros projetos do workspace
• tsconfig.json Uma referência de projeto TypeScript é adicionada para seu projeto

Escrevendo Código TypeScript

Adicione seu código TypeScript no diretório src.

Sintaxe de Importação ESM

Como seu projeto TypeScript é um Módulo ES, certifique-se de escrever suas declarações de importação com a sintaxe ESM correta, referenciando explicitamente a extensão do arquivo:

index.ts

import { sayHello } from './hello.js';

Nota

Apesar de estarmos usando TypeScript, e sayHello estar definido em hello.ts, usamos a extensão .js em nossa importação. Você pode ler mais sobre isso aqui.

Exportando para Outros Projetos TypeScript

O ponto de entrada do seu projeto TypeScript é src/index.ts. Você pode adicionar exports aqui para qualquer coisa que deseje que outros projetos possam importar:

src/index.ts

export { sayHello } from './hello.js';
export * from './algorithms/index.js';

Importando seu Código em Outros Projetos

Aliases TypeScript para seu projeto são configurados no tsconfig.base.json do workspace, permitindo que você referencie seu projeto TypeScript de outros projetos:

packages/my-other-project/src/index.ts

import { sayHello } from ':my-scope/my-library';

Nota

Aliases para projetos TypeScript começam com : ao invés do tradicional @, evitando conflitos de nomes entre pacotes locais do workspace e pacotes remotos no NPM.

Ao adicionar uma declaração de importação para um novo projeto em seu workspace pela primeira vez, você provavelmente verá um erro em sua IDE similar ao abaixo:

Erro de importação

File '/path/to/my/workspace/packages/my-library/src/index.ts' is not under 'rootDir' '/path/to/my/workspace/packages/my-consumer'. 'rootDir' is expected to contain all source files.
  File is ECMAScript module because '/path/to/my/workspace/package.json' has field "type" with value "module" ts(6059)
File '/path/to/my/workspace/packages/my-library/src/index.ts' is not listed within the file list of project '/path/to/my/workspace/packages/my-consumer/tsconfig.lib.json'. Projects must list all files or use an 'include' pattern.
  File is ECMAScript module because '/path/to/my/workspace/package.json' has field "type" with value "module" ts(6307)

Isso ocorre porque uma referência de projeto ainda não foi configurada.

Projetos TypeScript são configurados com o gerador Nx TypeScript Sync por padrão, dispensando a necessidade de configuração manual. Basta executar o seguinte comando e o Nx adicionará a configuração necessária:

pnpm

pnpm nx sync

yarn

yarn nx sync

npm

npx nx sync

bun

bunx nx sync

Após isso, o erro em sua IDE deve desaparecer e você estará pronto para usar sua biblioteca.

Dica

Você também pode simplesmente construir seu projeto e será apresentado uma mensagem como:

[@nx/js:typescript-sync]: Some TypeScript configuration files are missing project references to the projects they depend on or contain outdated project references.

This will result in an error in CI.

? Would you like to sync the identified changes to get your workspace up to date?
Yes, sync the changes and run the tasks
No, run the tasks without syncing the changes

Selecione Yes para permitir que o Nx atualize suas referências de projeto.

Dependências

Você notará que seu projeto TypeScript não possui um arquivo package.json, o que pode ser inesperado se você está acostumado com monorepos TypeScript tradicionais.

Para adicionar uma dependência a qualquer pacote TypeScript em seu monorepo, basta adicionar a dependência ao package.json na raiz do workspace. Você pode fazer isso via linha de comando do seu gerenciador de pacotes:

pnpm

pnpm add -w some-npm-package

yarn

yarn add some-npm-package

npm

npm install --legacy-peer-deps some-npm-package

bun

bun install some-npm-package

A dependência então fica disponível para todos os projetos TypeScript em seu workspace.

Código de Runtime

Ao usar seu projeto TypeScript como código de runtime (por exemplo, como handler de uma função AWS Lambda), recomenda-se usar uma ferramenta como esbuild para empacotar seu projeto, pois isso permite tree-shake para incluir apenas as dependências realmente utilizadas.

Você pode configurar isso adicionando um target como o seguinte em seu arquivo project.json:

{
  ...
  "targets": {
    ...
    "bundle": {
      "cache": true,
      "executor": "nx:run-commands",
      "outputs": ["{workspaceRoot}/dist/packages/my-library/bundle"],
      "options": {
        "command": "esbuild packages/my-library/src/index.ts --bundle --outfile=dist/packages/my-library/bundle/index.js --platform=node --format=cjs"
      }
    },
  },
}

Nota

Note que no target acima escolhemos src/index.ts como ponto de entrada do bundle, o que significa que o código exportado deste arquivo será incluído no bundle junto com todas suas dependências.

Publicação no NPM

Se você está publicando seu projeto TypeScript no NPM, deve criar um arquivo package.json para ele.

Este deve declarar todas as dependências utilizadas. Como durante o build o projeto resolve dependências instaladas via package.json raiz do workspace, recomenda-se configurar o ESLint Plugin Nx Dependency Checks para garantir que o package.json publicado inclua todas dependências usadas.

Build

Seu projeto TypeScript é configurado com um target build (definido em project.json), que pode ser executado via:

pnpm

pnpm nx run <project-name>:build

yarn

yarn nx run <project-name>:build

npm

npx nx run <project-name>:build

bun

bunx nx run <project-name>:build

Onde <project-name> é o nome completo qualificado do seu projeto.

O target build irá compilar, lintar e testar seu projeto.

A saída do build pode ser encontrada na pasta dist raiz do workspace, dentro de um diretório para seu pacote e target, por exemplo dist/packages/<my-library>/tsc

Testes

Vitest está configurado para testar seu projeto.

Escrevendo Testes

Testes devem ser escritos em arquivos .spec.ts ou .test.ts, colocalizados na pasta src do projeto.

Exemplo:

• Directorysrc

  • hello.ts Código da biblioteca
  • hello.spec.ts Testes para hello.ts

O Vitest fornece sintaxe estilo Jest para definir testes, com utilitários como describe, it, test e expect.

hello.spec.ts

import { sayHello } from './hello.js';

describe('sayHello', () => {

  it('deve cumprimentar o chamador', () => {
    expect(sayHello('Darth Vader')).toBe('Olá, Darth Vader!');
  });

});

Para mais detalhes sobre como escrever testes e recursos como mock de dependências, consulte a documentação do Vitest

Executando Testes

Testes são executados como parte do target build, mas você também pode executá-los separadamente via target test:

pnpm

pnpm nx run <project-name>:test

yarn

yarn nx run <project-name>:test

npm

npx nx run <project-name>:test

bun

bunx nx run <project-name>:test

Você pode executar um teste ou suite específica usando a flag -t:

pnpm

pnpm nx run <project-name>:test -t 'sayHello'

yarn

yarn nx run <project-name>:test -t 'sayHello'

npm

npx nx run <project-name>:test -t 'sayHello'

bun

bunx nx run <project-name>:test -t 'sayHello'

Dica

Usuários do VSCode podem instalar a extensão Vitest Runner for VSCode that actually works para executar, monitorar ou debugar testes diretamente da IDE.

Linting

Projetos TypeScript usam ESLint para linting e Prettier para formatação.

Recomendamos configurar o ESLint no arquivo eslint.config.mjs raiz do workspace, pois alterações aqui se aplicarão a todos projetos TypeScript e garantirão consistência.

Da mesma forma, você pode configurar o Prettier no arquivo .prettierrc raiz.

Executando o Linter

Para verificar seu projeto com o linter, execute o target lint:

pnpm

pnpm nx run <project-name>:lint

yarn

yarn nx run <project-name>:lint

npm

npx nx run <project-name>:lint

bun

bunx nx run <project-name>:lint

Corrigindo Problemas de Linting

A maioria dos problemas de linting/formatação pode ser corrigida automaticamente. Você pode pedir ao ESLint para corrigir problemas usando o argumento --configuration=fix:

pnpm

pnpm nx run <project-name>:lint --configuration=fix

yarn

yarn nx run <project-name>:lint --configuration=fix

npm

npx nx run <project-name>:lint --configuration=fix

bun

bunx nx run <project-name>:lint --configuration=fix

Similarmente, para corrigir todos problemas em todos pacotes do workspace:

pnpm

pnpm nx run-many --target lint --all --configuration=fix

yarn

yarn nx run-many --target lint --all --configuration=fix

npm

npx nx run-many --target lint --all --configuration=fix

bun

bunx nx run-many --target lint --all --configuration=fix