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 ESLint para análise estática.
Gerar um Projeto TypeScript
Seção intitulada “Gerar um Projeto TypeScript”Você pode gerar um novo projeto TypeScript de duas formas:
- Instale o Nx Console VSCode Plugin se ainda não o fez
- Abra o console Nx no VSCode
- Clique em
Generate (UI)
na seção "Common Nx Commands" - Procure por
@aws/nx-plugin - ts#project
- Preencha os parâmetros obrigatórios
- Clique em
Generate
pnpm nx g @aws/nx-plugin:ts#project
yarn nx g @aws/nx-plugin:ts#project
npx nx g @aws/nx-plugin:ts#project
bunx nx g @aws/nx-plugin:ts#project
Você também pode realizar uma execução simulada para ver quais arquivos seriam alterados
pnpm nx g @aws/nx-plugin:ts#project --dry-run
yarn nx g @aws/nx-plugin:ts#project --dry-run
npx nx g @aws/nx-plugin:ts#project --dry-run
bunx nx g @aws/nx-plugin:ts#project --dry-run
Parâmetro | Tipo | Padrão | Descrição |
---|---|---|---|
name Obrigatório | string | - | TypeScript project 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
Seção intitulada “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 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
- vite.config.ts Configuração do Vitest
- eslint.config.mjs Configuração do ESLint
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
Seção intitulada “Escrevendo Código TypeScript”Adicione seu código TypeScript no diretório src
.
Sintaxe de Importação ESM
Seção intitulada “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:
import { sayHello } from './hello.js';
Exportando para Outros Projetos TypeScript
Seção intitulada “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:
export { sayHello } from './hello.js';export * from './algorithms/index.js';
Importando seu Código em Outros Projetos
Seção intitulada “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:
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.
Projetos TypeScript são configurados com o gerador Nx TypeScript Sync por padrão, dispensando a necessidade de configurar manualmente as referências de projeto. Basta executar o seguinte comando e o Nx adicionará a configuração necessária:
pnpm nx sync
yarn nx sync
npx nx sync
bunx nx sync
Após isso, o erro em seu IDE deve desaparecer e você estará pronto para usar sua biblioteca.
Dependências
Seção intitulada “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 para 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 add -w some-npm-package
yarn add some-npm-package
npm install --legacy-peer-deps some-npm-package
bun install some-npm-package
A dependência estará então disponível para qualquer projeto TypeScript em seu workspace.
Código de Runtime
Seção intitulada “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:
import { defineConfig } from 'rolldown';
export default defineConfig([ { input: 'src/index.ts', output: { file: '../../dist/packages/my-library/bundle/index.js', format: 'cjs', inlineDynamicImports: true, }, },]);
Publicação no NPM
Seção intitulada “Publicação no NPM”Se você está publicando seu projeto TypeScript no NPM, deve criar um arquivo package.json
para ele.
Este deve declarar as dependências que seu projeto referencia. Como em tempo de build seu projeto resolve dependências instaladas via package.json
da raiz do workspace, recomenda-se configurar o Nx Dependency Checks ESLint Plugin para garantir que o package.json
do projeto publicado inclua todas dependências usadas.
Seu projeto TypeScript está configurado com um target build
(definido em project.json
), que pode ser executado via:
pnpm nx run <project-name>:build
yarn nx run <project-name>:build
npx nx run <project-name>:build
bunx nx run <project-name>:build
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
Vitest está configurado para testar seu projeto.
Escrevendo Testes
Seção intitulada “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
.
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
Seção intitulada “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 nx run <project-name>:test
yarn nx run <project-name>:test
npx nx run <project-name>:test
bunx nx run <project-name>:test
Você pode executar um teste individual ou suite de testes usando a flag -t
:
pnpm nx run <project-name>:test -t 'sayHello'
yarn nx run <project-name>:test -t 'sayHello'
npx nx run <project-name>:test -t 'sayHello'
bunx nx run <project-name>:test -t 'sayHello'
Linting
Seção intitulada “Linting”Projetos TypeScript usam ESLint para linting, junto com Prettier para formatação.
Recomendamos configurar o ESLint no arquivo eslint.config.mjs
da raiz do workspace, pois alterações aqui se aplicarão a todos projetos TypeScript no workspace garantindo consistência.
Da mesma forma, você pode configurar o Prettier no arquivo .prettierrc
da raiz.
Executando o Linter
Seção intitulada “Executando o Linter”Para invocar o linter e verificar seu projeto, execute o target lint
:
pnpm nx run <project-name>:lint
yarn nx run <project-name>:lint
npx nx run <project-name>:lint
bunx nx run <project-name>:lint
Corrigindo Problemas de Lint
Seção intitulada “Corrigindo Problemas de Lint”A maioria dos problemas de lint ou formatação podem ser corrigidos automaticamente. Você pode pedir ao ESLint para corrigir problemas de lint executando com o argumento --configuration=fix
:
pnpm nx run <project-name>:lint --configuration=fix
yarn nx run <project-name>:lint --configuration=fix
npx nx run <project-name>:lint --configuration=fix
bunx nx run <project-name>:lint --configuration=fix
Similarmente, se desejar corrigir todos problemas de lint em todos pacotes do workspace, execute:
pnpm nx run-many --target lint --all --configuration=fix
yarn nx run-many --target lint --all --configuration=fix
npx nx run-many --target lint --all --configuration=fix
bunx nx run-many --target lint --all --configuration=fix