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 Biome per il linting e la formattazione.

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	-	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 del progetto nella directory <directory>/<name>:

• Directorysrc Codice sorgente TypeScript

  • index.ts
• package.json Manifesto 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 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
• vitest.config.mts Configurazione per Vitest

Package.json del progetto

Il package.json del progetto inizia minimo. Man mano che aggiungi dipendenze runtime vengono dichiarate qui (gli strumenti di build/test condivisi rimangono nella root del workspace) — puoi scoprire di più 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';

Riferimenti TypeScript

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';

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, e il progetto importato non è stato ancora 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 è necessario configurarli manualmente. 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

 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 TypeScript sync di Nx aggiunge il riferimento di progetto, 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 durante l’installazione. Dopo questo passaggio, l’errore nel tuo IDE dovrebbe scomparire e sarai pronto a utilizzare la tua libreria.

Scorciatoia di build

Puoi anche semplicemente buildare il 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 gli alias di percorso sincronizzati

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 root.

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 del tuo package manager direttamente dalla directory del progetto.

Per aggiungere uno strumento di sviluppo condiviso, installalo nella root 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 garantisce 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 root.

Catalog

Per i package manager che supportano i catalog (pnpm, yarn e bun), i generatori registrano ogni versione nel catalog e la referenziano con il protocollo catalog: (ad es. "zod": "catalog:"), quindi il catalog è 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 deployment.

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

pnpm

Il workspace imposta catalogMode: strict, quindi pnpm add registra la versione nel catalog e la referenzia automaticamente — nessun passaggio aggiuntivo.

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

yarn

Il protocollo catalog: di yarn referenzia solo una voce di catalog 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. Referenziala dal progetto:

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

bun

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

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

   package.json

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

2. Referenziala dal progetto:

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

Allineamento delle versioni su npm

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

Disattivare i catalog

I catalog 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 catalog 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 root

Se preferisci dichiarare ogni dipendenza solo nel package.json root (senza dichiarazioni 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 root al momento della build, quindi tutto continua a funzionare — rinunci ai manifesti per progetto come registro accurato delle dipendenze di ciascun progetto (il che è importante se successivamente pubblichi un progetto o dividi il repository).

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,
    },
  },
]);

Configurazione del bundle

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.

Funzioni Lambda

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.

Build

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

Per buildare 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 utilizza 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 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 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 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 Biome per il linting e la formattazione. Biome è configurato nel file biome.json della root del workspace — le modifiche si applicano a tutti i progetti TypeScript nel workspace garantendo coerenza.

Eseguire il linter

Per invocare il linter e verificare il 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

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

Comando abbreviato

Questo ha un comando abbreviato dalla root 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 una 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 la build.

Comando abbreviato

Questo ha un comando abbreviato dalla root del tuo workspace:

pnpm

pnpm build:skip-lint

yarn

yarn build:skip-lint

npm

npm run build:skip-lint

bun

bun build:skip-lint