Progetti TypeScript

Il generatore di progetti TypeScript può essere utilizzato per creare una libreria o applicazione TypeScript moderna configurata con le best practice come ECMAScript Modules (ESM), project references di TypeScript, Vitest per l’esecuzione dei test e Biome per il linting e la formattazione.

Utilizzo

Generare un Progetto TypeScript

Puoi generare un nuovo progetto TypeScript in due modi:

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

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

Opzioni

Parametro	Tipo	Predefinito	Descrizione
name Obbligatorio	string	-	Nome del progetto TypeScript
directory	string	packages	Directory principale dove viene posizionata la libreria.
subDirectory	string	-	La sotto-directory in cui viene posizionata la libreria. Per impostazione predefinita corrisponde al nome della libreria.
preferInstallDependencies	boolean	true	Se preferire l'installazione delle dipendenze dopo l'esecuzione del generatore. Impostare su false per rimandare l'installazione quando si eseguono più generatori in batch (l'installazione viene comunque eseguita se necessaria affinché i generatori successivi possano calcolare il grafo dei progetti Nx); installare una volta alla fine.

Output del Generatore

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

• Directorysrc Codice sorgente TypeScript

  • index.ts
• package.json Manifest del progetto che definisce il nome del pacchetto e le dipendenze
• project.json Configurazione del progetto e target di build
• tsconfig.json Configurazione TypeScript di base per questo progetto (estende il tsconfig.base.json della radice del workspace)
• tsconfig.lib.json Configurazione TypeScript per la tua libreria (il tuo codice sorgente runtime o pacchettizzato)
• tsconfig.spec.json Configurazione TypeScript per i test
• vitest.config.mts Configurazione per Vitest

package.json del Progetto

Il package.json del progetto inizia minimale. Man mano che aggiungi dipendenze runtime, queste vengono dichiarate qui (gli strumenti di build/test condivisi rimangono nella radice del workspace) — puoi scoprire di più qui sotto.

Noterai anche alcune modifiche ai seguenti file nella radice del tuo workspace:

• nx.json La configurazione 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 tuo workspace
• tsconfig.json viene aggiunto un project reference TypeScript per il tuo progetto

Scrivere Codice Sorgente TypeScript

Aggiungi il tuo codice TypeScript nella directory src.

Sintassi Import ESM

Poiché il tuo progetto TypeScript è un ES Module, assicurati di scrivere le tue istruzioni import con la corretta sintassi ESM, facendo riferimento esplicito all’estensione del file:

index.ts

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

TypeScript References

Anche se stiamo usando TypeScript, e sayHello è definito in hello.ts, usiamo l’estensione .js nel nostro import. Puoi leggere di più su questo qui.

Esportare per Altri Progetti TypeScript

Il punto di ingresso per il tuo progetto TypeScript è src/index.ts. Puoi aggiungere export qui per tutto ciò che vorresti che altri progetti possano importare:

src/index.ts

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

Importare il Codice della Tua Libreria in Altri Progetti

Gli alias TypeScript per il tuo progetto sono configurati nel tsconfig.base.json del workspace, il che ti consente di fare riferimento al tuo progetto TypeScript da altri progetti TypeScript:

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

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

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

Errore di import

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 perché un project reference non è ancora stato configurato, e il progetto importato non è ancora stato dichiarato come dipendenza del workspace nel package.json del tuo progetto.

Il tuo workspace è configurato con generatori di sincronizzazione che gestiscono entrambi per te, quindi non devi configurarli manualmente. Esegui semplicemente il seguente comando e Nx aggiungerà la configurazione richiesta:

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!

Il generatore di sincronizzazione TypeScript di Nx aggiunge il project reference, e il generatore ts#sync del plugin dichiara il progetto importato nel package.json del tuo progetto (workspace:* dove il package manager supporta il protocollo workspace, * su npm e yarn classic), in modo che il package manager colleghi il progetto locale all’installazione. Dopo questo, l’errore nel tuo IDE dovrebbe scomparire e sei pronto per usare la tua libreria.

Scorciatoia Build

Puoi anche semplicemente fare il build del tuo progetto — i generatori di sincronizzazione vengono eseguiti per primi e ti verrà chiesto di applicare eventuali modifiche in sospeso:

 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

Seleziona Yes per consentire a Nx di sincronizzare il tuo workspace.

Mantenere Sincronizzati gli Alias dei Percorsi

Se aggiungi voci personalizzate compilerOptions.paths nel tsconfig.json di un progetto, TypeScript smette di ereditare gli alias del workspace definiti in tsconfig.base.json. Il generatore nascosto ts#sync viene eseguito prima del target compile (configurato in nx.json) per copiare eventuali alias di base mancanti nei file tsconfig.json, tsconfig.lib.json e tsconfig.app.json che già dichiarano paths. Per disattivare questa funzionalità, rimuovi @aws/nx-plugin:ts#sync da targetDefaults.compile.syncGenerators in nx.json.

Dipendenze

Ogni progetto TypeScript dichiara le proprie dipendenze runtime di terze parti nel proprio package.json. Gli strumenti di build e test condivisi tra i progetti sono definiti nel package.json radice.

Per aggiungere una dipendenza runtime a un progetto, installala in quel progetto:

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

Puoi anche eseguire il comando add/install semplice del tuo package manager dalla directory del progetto.

Per aggiungere uno strumento di sviluppo condiviso, installalo nella radice del 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

La regola di lint noUndeclaredDependencies di Biome impone che il codice sorgente di un progetto importi solo pacchetti dichiarati nel proprio package.json. I file di configurazione, gli script di build e i test sono esenti, quindi gli strumenti condivisi possono rimanere nella radice.

Cataloghi

Per i package manager che supportano i cataloghi (pnpm, yarn e bun), i generatori registrano ogni versione nel catalogo e vi fanno riferimento con il protocollo catalog: (es. "zod": "catalog:"), quindi il catalogo è l’unica fonte di verità per le versioni indipendentemente da quale progetto dichiara la dipendenza. Questo ti aiuta a seguire una single version policy, evitando conflitti di tipo e copie multiple di pacchetti nei bundle di distribuzione.

Quando aggiungi tu stesso una nuova dipendenza, mantienila anche nel catalogo:

pnpm

Il workspace imposta catalogMode: strict, quindi pnpm add registra la versione nel catalogo e vi fa riferimento automaticamente — nessun passaggio aggiuntivo.

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

yarn

Il protocollo catalog: di yarn fa solo riferimento a una voce di catalogo esistente — non può crearne una — quindi registra prima la versione.

1. Aggiungi la versione sotto catalog in .yarnrc.yml:

   .yarnrc.yml

   catalog:
     some-npm-package: ^1.0.0

2. Fai riferimento ad essa dal progetto:

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

bun

Il protocollo catalog: di bun fa solo riferimento a una voce di catalogo esistente — non può crearne una — quindi registra prima la versione.

1. Aggiungi la versione sotto catalog nel package.json radice:

   package.json

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

2. Fai riferimento ad essa dal progetto:

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

Allineare le versioni su npm

npm non ha una funzionalità di catalogo, quindi le versioni sono dichiarate direttamente in ogni package.json. Per mantenerle coerenti tra i progetti, raccomandiamo syncpack (npx syncpack lint).

Disattivare i cataloghi

I cataloghi sono abilitati per impostazione predefinita. Per disattivarli, crea il tuo workspace con --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

Oppure impostalo in aws-nx-plugin.config.mts in qualsiasi momento:

aws-nx-plugin.config.mts

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

Con i cataloghi disabilitati, i generatori scrivono le versioni delle dipendenze direttamente nel package.json di ogni progetto, e mantenere le versioni allineate tra i progetti è tua responsabilità.

Dichiarare tutte le dipendenze nella radice

Se preferisci dichiarare ogni dipendenza solo nel package.json radice (nessuna dichiarazione di dipendenze per progetto), disattiva la regola di lint nel biome.json del workspace:

biome.json

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

I progetti risolvono i pacchetti installati nella radice al momento del build, quindi tutto viene comunque compilato — rinunci ai manifest per progetto come registrazione accurata delle dipendenze di ogni progetto (il che è importante se successivamente pubblichi un progetto o dividi il repository).

Codice Runtime

Quando usi il tuo progetto TypeScript come codice runtime (ad esempio come handler per una funzione AWS Lambda), è consigliabile utilizzare uno strumento come Rolldown per raggruppare il tuo progetto, poiché questo può fare tree-shake per garantire che solo le dipendenze a cui il tuo progetto fa effettivamente riferimento siano incluse.

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

Configurazione del Bundle

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

Funzioni Lambda

Se stai costruendo una funzione AWS Lambda, dai un’occhiata al generatore ts#lambda-function poiché questo configura il bundling per te, oltre a generare l’infrastruttura e aggiungere osservabilità e type-safety.

Building

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

pnpm

pnpm nx build <project-name>

yarn

yarn nx build <project-name>

npm

npx nx build <project-name>

bun

bunx nx build <project-name>

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

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

L’output del build può essere trovato nella cartella dist radice nel tuo workspace, all’interno di una directory per il tuo pacchetto e target, ad esempio dist/packages/<my-library>/tsc

Per fare il build di tutti i progetti nel tuo workspace, esegui:

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

Oppure usa il comando abbreviato:

pnpm

pnpm build

yarn

yarn build

npm

npm run build

bun

bun build

Testing

Vitest è configurato per testare il tuo progetto.

Scrivere Test

I test dovrebbero essere scritti in file .spec.ts o .test.ts, co-locati nella cartella src del tuo progetto.

Ad 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 per il tuo progetto, ma puoi anche eseguirli separatamente eseguendo il 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>

Puoi eseguire un singolo test o una suite di test usando il flag -t di Vitest. Passalo dopo un separatore -- in modo che Nx lo inoltri a Vitest invece di interpretarlo come la propria opzione --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'

Integrazione VSCode

Se sei un utente VSCode, raccomandiamo di installare l’estensione Vitest Runner for VSCode that actually works, che ti consente di eseguire, osservare o debuggare i test dal tuo IDE.

Linting

I progetti TypeScript usano Biome per il linting e la formattazione. Biome è configurato nel file biome.json della radice del workspace — le modifiche a questo si applicano a tutti i progetti TypeScript nel tuo workspace e garantiscono coerenza.

Eseguire il Linter

Per invocare il linter per controllare il tuo progetto, puoi eseguire il 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>

Correggere i Problemi di Lint

La maggior parte dei problemi di linting o formattazione può essere corretta automaticamente eseguendo con l’argomento --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

Allo stesso modo, se desideri correggere tutti i problemi di lint in tutti i pacchetti nel tuo 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

Comando Abbreviato

Questo ha un comando abbreviato dalla radice del tuo workspace:

pnpm

pnpm lint

yarn

yarn lint

npm

npm run lint

bun

bun lint

Saltare i Problemi di Lint

Per evitare che i problemi di linting ti rallentino durante lo sviluppo (in particolare se hai problemi non auto-correggibili nel tuo progetto), puoi eseguire un build con la configurazione 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

Questo salta completamente il target lint durante il build.

Comando Abbreviato

Questo ha un comando abbreviato dalla radice del tuo workspace:

pnpm

pnpm build:skip-lint

yarn

yarn build:skip-lint

npm

npm run build:skip-lint

bun

bun build:skip-lint