Pular para o conteúdo

Projetos TypeScript

O gerador de projetos TypeScript pode ser usado para criar uma biblioteca ou aplicação moderna em TypeScript configurada 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.

Uso

Gerar um Projeto TypeScript

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

  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
    • Clique em Generate

    Opções

    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

    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 TypeScript é configurado para seu projeto permitindo 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 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';

    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 deseje disponibilizar para outros projetos:

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

    Importando Código da Biblioteca em Outros Projetos

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

    packages/my-other-project/src/index.ts
    import { sayHello } from ':my-scope/my-library';

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

    Erro de importação
    Terminal window
    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, eliminando a necessidade de configurar manualmente as referências. Basta executar o seguinte comando para o Nx adicionar a configuração necessária:

    Terminal window
    pnpm nx sync

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

    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 adicioná-la ao package.json na raiz do workspace. Você pode fazer isso via linha de comando do seu gerenciador de pacotes:

    Terminal window
    pnpm add -w some-npm-package

    A dependência ficará 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 ferramentas como esbuild para empacotar o projeto, pois isso permite tree-shake para incluir apenas dependências realmente utilizadas.

    Você pode configurar isso adicionando um target 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": "esbuild packages/my-library/src/index.ts --bundle --outfile=dist/packages/my-library/bundle/index.js --platform=node --format=cjs"
    }
    },
    },
    }

    Publicação no NPM

    Se for publicar seu projeto TypeScript no NPM, você deve criar um arquivo package.json para ele.

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

    Build

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

    Terminal window
    pnpm nx run <project-name>:build

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

    O target build compilará, fará lint e testará seu projeto.

    A saída do build estará na pasta dist da 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 testes em 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 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('should greet the caller', () => {
    expect(sayHello('Darth Vader')).toBe('Hello, Darth Vader!');
    });
    });

    Para detalhes sobre escrita de 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ê pode executá-los separadamente usando o target test:

    Terminal window
    pnpm nx run <project-name>:test

    Você pode executar um teste individual ou suite usando a flag -t:

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

    Linting

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

    Recomendamos configurar o ESLint no arquivo eslint.config.mjs da raiz do workspace, garantindo consistência entre todos projetos.

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

    Executando o Linter

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

    Terminal window
    pnpm nx run <project-name>:lint

    Corrigindo Problemas de Lint

    A maioria dos problemas de linting/formatação podem ser corrigidos automaticamente. Use o argumento --configuration=fix para aplicar correções:

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

    Para corrigir todos os problemas em todos pacotes do workspace:

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