Progetti TypeScript

Il generatore di progetti TypeScript può essere utilizzato per creare una libreria o un’applicazione moderna TypeScript configurata con le migliori pratiche come ECMAScript Modules (ESM), i riferimenti di progetto di TypeScript, Vitest per l’esecuzione dei test e ESLint per l’analisi statica.

Utilizzo

Genera un progetto TypeScript

Puoi generare un nuovo progetto TypeScript in due modi:

VSCode

1. Installa il Nx Console VSCode Plugin se non l'hai già fatto
2. Apri la console Nx in VSCode
3. Clicca su Generate (UI) nella sezione "Common Nx Commands"
4. Cerca @aws/nx-plugin - ts#project
5. Compila i parametri richiesti
6. Clicca su 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

Puoi anche eseguire una prova per vedere quali file verrebbero modificati

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

Opzioni

Parametro	Tipo	Predefinito	Descrizione
name Obbligatorio	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.

Output del generatore

Il generatore creerà la seguente struttura del progetto nella directory <directory>/<name>:

• Directorysrc Codice sorgente TypeScript

  • index.ts
• project.json Configurazione del progetto e target di build
• tsconfig.json Configurazione TypeScript di base per questo progetto (estende tsconfig.base.json nella root del workspace)
• tsconfig.lib.json Configurazione TypeScript per la tua libreria (codice runtime o sorgente impacchettato)
• tsconfig.spec.json Configurazione TypeScript per i test
• vite.config.ts Configurazione per Vitest
• eslint.config.mjs Configurazione per ESLint

Consiglio

Nota che non viene creato alcun file package.json per questo progetto! Puoi scoprire il motivo qui sotto.

Noterai anche alcune modifiche ai seguenti file nella root del workspace:

• nx.json La configurazione di Nx viene aggiornata per configurare il plugin @nx/js/typescript per il tuo progetto
• tsconfig.base.json Viene impostato un alias TypeScript per il tuo progetto in modo che possa essere importato da altri progetti nel workspace
• tsconfig.json Viene aggiunto un riferimento di progetto TypeScript per il tuo progetto

Scrivere codice TypeScript

Aggiungi il tuo codice TypeScript nella directory src.

Sintassi di import ESM

Poiché il tuo progetto TypeScript è un ES Module, assicurati di scrivere le istruzioni di import con la corretta sintassi ESM, riferendo esplicitamente l’estensione del file:

index.ts

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

Nota

Anche se stiamo usando TypeScript e sayHello è definito in hello.ts, utilizziamo l’estensione .js nel nostro import. Puoi leggere maggiori dettagli qui.

Esportare per altri progetti TypeScript

Il punto di ingresso per il tuo progetto TypeScript è src/index.ts. Puoi aggiungere qui le esportazioni per qualsiasi elemento che desideri rendere disponibile ad altri progetti:

src/index.ts

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

Importare il codice della libreria in altri progetti

Gli alias TypeScript per il tuo progetto sono configurati nel tsconfig.base.json del workspace, consentendo di riferire il tuo progetto TypeScript da altri progetti TypeScript:

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

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

Nota

Gli alias per i progetti TypeScript iniziano con : invece del tradizionale @, per evitare possibili conflitti di nome tra pacchetti locali nel workspace e pacchetti remoti su NPM.

Quando aggiungi un’istruzione di import per un nuovo progetto nel workspace per la prima volta, potresti vedere un errore nel tuo IDE simile al seguente:

Errore di importazione

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)

Questo accade perché non è stato configurato un riferimento di progetto.

I progetti TypeScript sono configurati con il generatore Nx TypeScript Sync out-of-the-box, evitando la necessità di configurare manualmente i riferimenti. Esegui semplicemente il seguente comando e Nx aggiungerà la configurazione necessaria:

pnpm

pnpm nx sync

yarn

yarn nx sync

npm

npx nx sync

bun

bunx nx sync

Dopo questo passaggio, l’errore nel tuo IDE dovrebbe scomparire e sarai pronto a utilizzare la tua libreria.

Consiglio

Puoi anche semplicemente buildare il tuo progetto e vedrai un messaggio come:

[@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

Seleziona Yes per consentire a Nx di aggiornare i riferimenti del progetto.

Dipendenze

Noterai che il tuo progetto TypeScript non ha un file package.json, cosa che potrebbe sorprendere se sei abituato a monorepo TypeScript tradizionali.

Per aggiungere una dipendenza a un pacchetto TypeScript nel tuo monorepo, aggiungi semplicemente la dipendenza al package.json nella root del workspace. Puoi farlo tramite la linea di comando del tuo package manager:

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

La dipendenza sarà quindi disponibile per qualsiasi progetto TypeScript nel workspace.

Codice runtime

Quando utilizzi il tuo progetto TypeScript come codice runtime (ad esempio come handler per una funzione AWS Lambda), è consigliato utilizzare uno strumento come Rolldown per bundle del progetto, poiché permette di effettuare tree-shaking per includere solo le dipendenze effettivamente utilizzate.

Puoi ottenere questo aggiungendo un target come il seguente nel tuo file 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 aggiungendo il file rolldown.config.ts come 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,
    },
  },
]);

Nota

Nota che nel target sopra abbiamo scelto src/index.ts come entrypoint per il bundle, il che significa che il codice esportato da questo file sarà incluso nel bundle, insieme a tutte le sue dipendenze.

Consiglio

Se stai costruendo una funzione AWS Lambda, consulta il generatore ts#lambda-function che configura il bundling automaticamente, oltre a generare l’infrastruttura e aggiungere osservabilità e type-safety.

Pubblicazione su NPM

Se pubblichi il tuo progetto TypeScript su NPM, devi creare un file package.json per esso.

Questo deve dichiarare le dipendenze utilizzate dal progetto. Poiché al momento della build le dipendenze vengono risolte tramite il package.json della root del workspace, è consigliato configurare il Nx Dependency Checks ESLint Plugin per assicurarsi che il package.json del progetto pubblicato includa tutte le dipendenze utilizzate.

Build

Il tuo progetto TypeScript è configurato con un target build (definito in project.json), che puoi eseguire tramite:

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

Dove <project-name> è il nome completo del tuo progetto.

Il target build compilerà, eseguirà il lint e testerà il progetto.

L’output della build si trova nella cartella dist della root del workspace, all’interno di una directory specifica per il pacchetto e il target, ad esempio dist/packages/<my-library>/tsc

Testing

Vitest è configurato per testare il tuo progetto.

Scrivere test

I test devono essere scritti in file .spec.ts o .test.ts, posizionati nella cartella src del progetto.

Esempio:

• Directorysrc

  • hello.ts Codice sorgente della libreria
  • hello.spec.ts Test per hello.ts

Vitest fornisce una sintassi simile a Jest per definire i test, con utility come 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!');
  });

});

Per maggiori dettagli su come scrivere test e funzionalità come il mocking delle dipendenze, consulta la documentazione di Vitest

Eseguire i test

I test verranno eseguiti come parte del target build del progetto, ma puoi anche eseguirli separatamente con il 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

Puoi eseguire un singolo test o una suite di test usando il 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'

Consiglio

Se utilizzi VSCode, ti consigliamo di installare l’estensione Vitest Runner for VSCode that actually works, che permette di eseguire, monitorare o debuggare i test direttamente dall’IDE.

Linting

I progetti TypeScript utilizzano ESLint per il linting, insieme a Prettier per la formattazione.

Consigliamo di configurare ESLint nel file eslint.config.mjs della root del workspace, in modo che le modifiche si applichino a tutti i progetti TypeScript nel workspace garantendo coerenza.

Allo stesso modo, puoi configurare Prettier nel file .prettierrc della root.

Eseguire il linter

Per invocare il linter e verificare il progetto, puoi eseguire il 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

Correggere i problemi di lint

La maggior parte dei problemi di linting o formattazione può essere corretta automaticamente. Puoi chiedere a ESLint di correggere i problemi eseguendo con l’argomento --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

Analogamente, se vuoi correggere tutti i problemi di lint in tutti i pacchetti del workspace, puoi eseguire:

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