Projetos TypeScript

O gerador de projetos TypeScript pode ser usado para criar uma biblioteca ou aplicação TypeScript moderna configurada com as melhores práticas, como ECMAScript Modules (ESM), referências de projeto do TypeScript, Vitest para executar testes e Biome para linting e formatação.

Uso

Gerar um Projeto TypeScript

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

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

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

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 alvos 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 (seu código-fonte de runtime ou empacotado)
• tsconfig.spec.json Configuração do TypeScript para seus testes
• vitest.config.mts Configuração para o 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á algumas mudanças nos seguintes arquivos na raiz do seu workspace:

• nx.json A configuração do Nx é atualizada para configurar o plugin @nx/js/typescript para o seu projeto
• tsconfig.base.json um alias do TypeScript é configurado para o seu projeto para que ele possa ser importado por outros projetos no seu workspace
• tsconfig.json uma referência de projeto do TypeScript é adicionada para o seu projeto

Escrevendo Código-Fonte 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 declaraçõ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

Mesmo que estejamos usando TypeScript, e sayHello esteja definido em hello.ts, usamos a extensão de arquivo .js em nossa importação. Você pode ler mais sobre isso aqui.

Exportando para Outros Projetos TypeScript

O ponto de entrada para o seu projeto TypeScript é src/index.ts. Você pode adicionar exportações aqui para qualquer coisa que você gostaria que outros projetos pudessem importar:

src/index.ts

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

Importando o Código da Sua Biblioteca em Outros Projetos

Aliases do TypeScript para o seu projeto são configurados no tsconfig.base.json do workspace, o que permite 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 declaração de importação para um novo projeto no seu workspace pela primeira vez, você provavelmente verá um erro no seu IDE semelhante 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, e o projeto importado ainda não foi declarado como uma dependência do 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. Simplesmente execute 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 de sincronização do TypeScript do Nx adiciona a referência do 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 workspace, * no npm e yarn classic), para que o gerenciador de pacotes vincule o projeto local na instalação. Depois disso, o erro no seu IDE deve desaparecer e você está pronto para usar sua biblioteca.

Atalho de Build

Você também pode simplesmente fazer o build do 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 os Aliases de Caminho Sincronizados

Se você adicionar entradas personalizadas de 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 alvo 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 simples add/install do seu gerenciador de pacotes de dentro do diretório do projeto.

Para adicionar uma ferramenta de desenvolvimento 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: (por exemplo, "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 por conta própria, 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

O npm não tem 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

Os 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 defina-o em aws-nx-plugin.config.mts a qualquer momento:

aws-nx-plugin.config.mts

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

Com os catálogos desabilitados, os geradores escrevem versões de dependências diretamente no package.json de cada projeto, e manter as 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"
      }
    }
  }
}

Os projetos resolvem pacotes instalados na raiz no momento do build, então tudo ainda é construído — 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

Quando você usa seu projeto TypeScript como código de runtime (por exemplo, como o handler para uma função AWS Lambda), é recomendado que você use uma ferramenta como Rolldown para empacotar seu projeto, pois isso pode fazer tree-shake para garantir que apenas as dependências que seu projeto realmente referencia sejam incluídas.

Você pode conseguir isso adicionando um alvo como o seguinte ao 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 da seguinte forma:

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',
      codeSplitting: false,
    },
  },
]);

Configuração de Bundle

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

Funções Lambda

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

Build

Seu projeto TypeScript está configurado com um alvo build (definido em project.json), que você pode executar 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 alvo build irá compilar, fazer lint e testar seu projeto.

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

Para fazer o build de todos os projetos no 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

Os testes devem ser escritos em arquivos .spec.ts ou .test.ts, co-localizados 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 semelhante 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('should greet the caller', () => {
    expect(sayHello('Darth Vader')).toBe('Hello, Darth Vader!');
  });

});

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

Executando Testes

Os testes serão executados como parte do alvo build para o seu projeto, mas você também pode executá-los separadamente executando o alvo 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 conjunto de testes usando a flag -t do Vitest. Passe-a após um separador -- para que o Nx a encaminhe para o Vitest em vez 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 com VSCode

Se você é um usuário do VSCode, recomendamos instalar a extensão Vitest Runner for VSCode that actually works, que permite executar, observar ou depurar testes do seu IDE.

Linting

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

Executando o Linter

Para invocar o linter para verificar seu projeto, você pode executar o alvo 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 linting ou formatação pode ser corrigida 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

Da mesma forma, se você gostaria de corrigir todos os problemas de lint em todos os pacotes no seu workspace, você pode executar:

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

Isso tem um comando abreviado 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 linting o atrasem durante o desenvolvimento (particularmente se você tiver problemas não corrigíveis automaticamente no 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 ignora o alvo de lint inteiramente durante o build.

Comando Abreviado

Isso tem um comando abreviado 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