Salta ai contenuti

Progetti TypeScript

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

Utilizzo

Generare un Progetto TypeScript

Puoi generare un nuovo progetto TypeScript in due modi:

  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
    • Clicca su Generate

    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 base per questo progetto (estende tsconfig.base.json della root del workspace)
    • tsconfig.lib.json Configurazione TypeScript per la tua libreria (codice runtime o da pubblicare)
    • tsconfig.spec.json Configurazione TypeScript per i test
    • vite.config.ts Configurazione per Vitest
    • eslint.config.mjs Configurazione per ESLint

    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 per consentirne l’importazione da altri progetti nel workspace
    • tsconfig.json Viene aggiunto un riferimento al progetto TypeScript

    Scrivere Codice TypeScript

    Aggiungi il tuo codice TypeScript nella directory src.

    Sintassi di Importazione ESM

    Poiché il tuo progetto TypeScript è un Modulo ES, assicurati di scrivere le istruzioni di importazione con la sintassi ESM corretta, riferendoti esplicitamente all’estensione del file:

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

    Esportare per Altri Progetti TypeScript

    Il punto di ingresso del 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 file tsconfig.base.json del workspace, permettendoti di riferirti al 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
    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)

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

    I progetti TypeScript sono preconfigurati con il generatore Nx TypeScript Sync, evitandoti di dover configurare manualmente i riferimenti. Esegui semplicemente il seguente comando e Nx aggiungerà la configurazione necessaria:

    Terminal window
    pnpm nx sync

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

    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 qualsiasi pacchetto TypeScript nel tuo monorepo, aggiungi semplicemente la dipendenza al package.json nella root del workspace. Puoi farlo tramite la riga di comando del tuo package manager:

    Terminal window
    pnpm add -w some-npm-package

    La dipendenza sarà quindi disponibile per tutti i progetti TypeScript nel workspace.

    Codice Runtime

    Quando utilizzi il tuo progetto TypeScript come codice runtime (ad esempio come handler per una funzione AWS Lambda), si consiglia di utilizzare uno strumento come esbuild per creare un bundle del progetto, poiché può effettuare il tree-shaking per includere solo le dipendenze effettivamente utilizzate.

    Puoi ottenere questo aggiungendo un target come il seguente al tuo file 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"
    }
    },
    },
    }

    Pubblicazione su NPM

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

    Questo deve dichiarare tutte le dipendenze utilizzate dal progetto. Poiché durante la build le dipendenze vengono risolte tramite il package.json della root del workspace, si consiglia di configurare il Plugin ESLint per i Controlli delle Dipendenze di Nx per assicurarti 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:

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

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

    Il target build compilerà, eseguirà il linting e i test del progetto.

    L’output della build si troverà 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 eseguire i test del progetto.

    Scrivere Test

    I test dovrebbero 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 Test

    I test verranno eseguiti come parte del target build del progetto, ma puoi anche eseguirli separatamente tramite il target test:

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

    Puoi eseguire un singolo test o una suite di test utilizzando il flag -t:

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

    Linting

    I progetti TypeScript utilizzano ESLint per il linting e 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:

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

    Correggere Problemi di Linting

    La maggior parte dei problemi di linting o formattazione può essere corretta automaticamente. Puoi chiedere a ESLint di correggere i problemi eseguendolo con l’argomento --configuration=fix:

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

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

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