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 ECMAScript Modules (ESM), project references do TypeScript, Vitest para execução de testes e Biome para linting e formatação.

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	-	Nome do projeto TypeScript
directory	string	packages	Diretório pai onde a biblioteca é colocada.
subDirectory	string	-	O subdiretório onde a biblioteca é colocada. Por padrão, este é o nome da biblioteca.
preferInstallDependencies	boolean	true	Se deve preferir instalar dependências após a execução do gerador. Defina como false para adiar a instalação ao executar múltiplos geradores em lote (uma instalação ainda é executada se necessário para que geradores subsequentes possam calcular o grafo de projetos Nx); instale uma vez no final.

Saída do Gerador

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

• Directorysrc Código-fonte TypeScript

  • index.ts
• package.json Manifesto do projeto definindo o nome do pacote e dependências do projeto
• project.json Configuração do projeto e targets de build
• tsconfig.json Configuração base do TypeScript para este projeto (estende o tsconfig.base.json da raiz do workspace)
• tsconfig.lib.json Configuração do TypeScript para sua biblioteca (código de runtime ou empacotado)
• tsconfig.spec.json Configuração do TypeScript para seus testes
• vitest.config.mts Configuração do Vitest

package.json do projeto

O package.json do projeto começa mínimo. À medida que você adiciona dependências de runtime, elas são declaradas aqui (ferramentas compartilhadas de build/teste permanecem na raiz do workspace) — você pode descobrir mais 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 do TypeScript é configurado para seu projeto permitindo sua importação por outros projetos no 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 ES Module, certifique-se de escrever suas instruções de importação com a sintaxe ESM correta, referenciando explicitamente a extensão do arquivo:

index.ts

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

Referências TypeScript

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 elemento que deseja 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

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

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

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

Quando você adiciona uma instrução de importação para um novo projeto em seu workspace pela primeira vez, provavelmente verá um erro em seu 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 project reference ainda não foi configurada, e o projeto importado ainda não foi declarado como uma dependência de workspace no package.json do seu projeto.

Seu workspace está configurado com geradores de sincronização que gerenciam ambos para você, então você não precisa configurá-los manualmente. 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

 NX   The workspace is out of sync

[@nx/js:typescript-sync]: Some TypeScript configuration files are missing project references to the projects they depend on, contain stale project references, or have duplicate project references.
[@aws/nx-plugin:ts#sync]: Local project dependencies are out of sync. The following workspace dependencies will be declared:
packages/my-other-project/package.json:
- @my-scope/my-library: workspace:*

Syncing the workspace...
The workspace was synced successfully!

O gerador TypeScript sync do Nx adiciona a referência de projeto, e o gerador ts#sync do plugin declara o projeto importado no package.json do seu projeto (workspace:* onde o gerenciador de pacotes suporta o protocolo de workspace, * no npm e yarn classic), para que o gerenciador de pacotes vincule o projeto local na instalação. Após isso, o erro em seu IDE deve desaparecer e você estará pronto para usar sua biblioteca.

Atalho de compilação

Você também pode simplesmente construir seu projeto — os geradores de sincronização são executados primeiro e você será solicitado a aplicar quaisquer alterações pendentes:

 NX   The workspace is out of sync

...

? 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 sincronize seu workspace.

Mantendo Aliases de Path Sincronizados

Se você adicionar entradas personalizadas em compilerOptions.paths no tsconfig.json de um projeto, o TypeScript para de herdar os aliases do workspace definidos em tsconfig.base.json. O gerador oculto ts#sync é executado antes do target compile (configurado em nx.json) para copiar quaisquer aliases base ausentes nos arquivos tsconfig.json, tsconfig.lib.json e tsconfig.app.json que já declaram paths. Para desativar, remova @aws/nx-plugin:ts#sync de targetDefaults.compile.syncGenerators em nx.json.

Dependências

Cada projeto TypeScript declara suas dependências de runtime de terceiros em seu próprio package.json. Ferramentas de build e teste compartilhadas entre projetos são definidas no package.json raiz.

Para adicionar uma dependência de runtime a um projeto, instale-a nesse projeto:

pnpm

pnpm add some-npm-package --filter my-library

yarn

yarn workspace @my-scope/my-library add some-npm-package

npm

npm install --legacy-peer-deps some-npm-package -w packages/my-library

bun

bun add some-npm-package --cwd packages/my-library

Você também pode executar o comando add/install simples do seu gerenciador de pacotes de dentro do diretório do projeto.

Para adicionar uma ferramenta de dev compartilhada, instale-a na raiz do workspace:

pnpm

pnpm add -Dw some-dev-tool

yarn

yarn add -D some-dev-tool

npm

npm install --legacy-peer-deps -D some-dev-tool

bun

bun add -D some-dev-tool

Nota

A regra de lint noUndeclaredDependencies do Biome garante que o código-fonte de um projeto importe apenas pacotes declarados em seu próprio package.json. Arquivos de configuração, scripts de build e testes são isentos, então ferramentas compartilhadas podem permanecer na raiz.

Catálogos

Para gerenciadores de pacotes que suportam catálogos (pnpm, yarn e bun), os geradores registram cada versão no catálogo e a referenciam com o protocolo catalog: (ex. "zod": "catalog:"), então o catálogo é a única fonte de verdade para versões independentemente de qual projeto declara a dependência. Isso ajuda você a seguir uma política de versão única, evitando conflitos de tipo e múltiplas cópias de pacotes em bundles de implantação.

Quando você adicionar uma nova dependência, mantenha-a no catálogo também:

pnpm

O workspace define catalogMode: strict, então pnpm add registra a versão no catálogo e a referencia automaticamente — sem etapas extras.

pnpm add some-npm-package --filter my-library

yarn

O protocolo catalog: do yarn apenas referencia uma entrada de catálogo existente — ele não pode criar uma — então registre a versão primeiro.

1. Adicione a versão sob catalog em .yarnrc.yml:

   .yarnrc.yml

   catalog:
     some-npm-package: ^1.0.0

2. Referencie-a do projeto:

   yarn workspace @my-scope/my-library add some-npm-package@catalog:

bun

O protocolo catalog: do bun apenas referencia uma entrada de catálogo existente — ele não pode criar uma — então registre a versão primeiro.

1. Adicione a versão sob catalog no package.json raiz:

   package.json

   {
     "catalog": {
       "some-npm-package": "^1.0.0"
     }
   }

2. Referencie-a do projeto:

   bun add some-npm-package@catalog: --cwd packages/my-library

Alinhando versões no npm

npm não possui recurso de catálogo, então as versões são declaradas diretamente em cada package.json. Para mantê-las consistentes entre projetos, recomendamos syncpack (npx syncpack lint).

Desativando catálogos

Catálogos são habilitados por padrão. Para desativá-los, crie seu workspace com --catalog false:

pnpm

pnpm create @aws/nx-workspace my-project --catalog false

yarn

yarn create @aws/nx-workspace my-project --catalog false

npm

npm create @aws/nx-workspace -- my-project --catalog false

bun

bun create @aws/nx-workspace my-project --catalog false

Ou configure em aws-nx-plugin.config.mts a qualquer momento:

aws-nx-plugin.config.mts

export default {
  packageManager: {
    catalogs: false,
  },
} satisfies AwsNxPluginConfig;

Com catálogos desabilitados, os geradores escrevem versões de dependências diretamente no package.json de cada projeto, e manter versões alinhadas entre projetos é sua responsabilidade.

Declarando todas as dependências na raiz

Se você preferir declarar todas as dependências apenas no package.json raiz (sem declarações de dependências por projeto), desative a regra de lint no biome.json do workspace:

biome.json

{
  "linter": {
    "rules": {
      "correctness": {
        "noUndeclaredDependencies": "off"
      }
    }
  }
}

Projetos resolvem pacotes instalados na raiz em tempo de build, então tudo ainda compila — você abre mão de manifestos por projeto como um registro preciso das dependências de cada projeto (o que importa se você posteriormente publicar um projeto ou dividir o repositório).

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 Rolldown para empacotar seu projeto, pois isso permite tree-shake para incluir apenas as dependências realmente utilizadas.

Você pode alcançar 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": "rolldown -c rolldown.config.ts"
      }
    },
  },
}

E adicionando o arquivo rolldown.config.ts como segue:

rolldown.config.ts

import { defineConfig } from 'rolldown';

export default defineConfig([
  {
    input: 'src/index.ts',
    output: {
      file: '../../dist/packages/my-library/bundle/index.js',
      format: 'cjs',
      inlineDynamicImports: true,
    },
  },
]);

Configuração de empacotamento

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

Funções Lambda

Se estiver construindo uma função AWS Lambda, confira o gerador ts#lambda-function pois ele configura o empacotamento automaticamente, além de gerar infraestrutura e adicionar observabilidade e type-safety.

Building

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

pnpm

pnpm nx build <project-name>

yarn

yarn nx build <project-name>

npm

npx nx build <project-name>

bun

bunx nx build <project-name>

Onde <project-name> é o nome totalmente 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 da raiz do workspace, dentro de um diretório para seu pacote e target, por exemplo dist/packages/<my-library>/tsc

Para construir todos os projetos em seu workspace, execute:

pnpm

pnpm nx run-many --target build

yarn

yarn nx run-many --target build

npm

npx nx run-many --target build

bun

bunx nx run-many --target build

Ou use o comando abreviado:

pnpm

pnpm build

yarn

yarn build

npm

npm run build

bun

bun build

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 seu projeto.

Por exemplo:

• Directorysrc

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

O Vitest fornece sintaxe similar ao 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('Hello, Darth Vader!');
  });

});

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

Executando Testes

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

pnpm

pnpm nx test <project-name>

yarn

yarn nx test <project-name>

npm

npx nx test <project-name>

bun

bunx nx test <project-name>

Você pode executar um teste individual ou suite de testes usando a flag -t do Vitest. Passe-a após um separador -- para que o Nx a encaminhe ao Vitest ao invés de consumi-la como sua própria opção --target:

pnpm

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

yarn

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

npm

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

bun

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

Integração VSCode

Se você usa VSCode, recomendamos instalar a extensão Vitest Runner for VSCode that actually works, que permite executar, monitorar ou debugar testes diretamente da IDE.

Linting

Projetos TypeScript usam Biome para linting e formatação. O Biome é configurado no arquivo biome.json da raiz do workspace — alterações aqui se aplicam a todos os projetos TypeScript no workspace garantindo consistência.

Executando o Linter

Para invocar o linter e verificar seu projeto, execute o target lint:

pnpm

pnpm nx lint <project-name>

yarn

yarn nx lint <project-name>

npm

npx nx lint <project-name>

bun

bunx nx lint <project-name>

Corrigindo Problemas de Lint

A maioria dos problemas de lint ou formatação podem ser corrigidos automaticamente executando com o argumento --configuration=fix.

pnpm

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

yarn

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

npm

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

bun

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

Similarmente, se desejar corrigir todos problemas de lint em todos pacotes do workspace, execute:

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

Comando abreviado

Isto possui um comando abreviado a partir da raiz do seu workspace:

pnpm

pnpm lint

yarn

yarn lint

npm

npm run lint

bun

bun lint

Ignorando Problemas de Lint

Para evitar que problemas de lint atrasem você durante o desenvolvimento (particularmente se você tem problemas não corrigíveis automaticamente em seu projeto), você pode executar um build com a configuração skip-lint:

pnpm

pnpm nx run-many --target build --configuration=skip-lint

yarn

yarn nx run-many --target build --configuration=skip-lint

npm

npx nx run-many --target build --configuration=skip-lint

bun

bunx nx run-many --target build --configuration=skip-lint

Isso pula o target de lint completamente durante o build.

Comando abreviado

Isto possui um comando abreviado a partir da raiz do seu workspace:

pnpm

pnpm build:skip-lint

yarn

yarn build:skip-lint

npm

npm run build:skip-lint

bun

bun build:skip-lint