Contribuisci a un Generatore

Creiamo un nuovo generatore da contribuire a @aws/nx-plugin. Il nostro obiettivo sarà generare una nuova procedura per un’API tRPC.

Esplora il Plugin

Per prima cosa, cloniamo il plugin:

git clone git@github.com:awslabs/nx-plugin-for-aws.git

Quindi installiamo e compiliamo:

cd nx-plugin-for-aws
pnpm i
pnpm nx run-many --target build --all

Crea un Generatore Vuoto

Creiamo il nuovo generatore in packages/nx-plugin/src/trpc/procedure.

Forniamo un generatore per creare nuovi generatori, così puoi scaffoldare rapidamente il tuo nuovo generatore! Puoi eseguire questo generatore come segue:

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#nx-generator
5. Compila i parametri richiesti
   • pluginProject: @aws/nx-plugin
   • name: ts#trpc-api#procedure
   • directory: trpc/procedure
   • description: Adds a procedure to a tRPC API
6. Clicca su Generate

CLI

pnpm

pnpm nx g @aws/nx-plugin:ts#nx-generator --pluginProject=@aws/nx-plugin --name=ts#trpc-api#procedure --directory=trpc/procedure --description=Adds a procedure to a tRPC API

yarn

yarn nx g @aws/nx-plugin:ts#nx-generator --pluginProject=@aws/nx-plugin --name=ts#trpc-api#procedure --directory=trpc/procedure --description=Adds a procedure to a tRPC API

npm

npx nx g @aws/nx-plugin:ts#nx-generator --pluginProject=@aws/nx-plugin --name=ts#trpc-api#procedure --directory=trpc/procedure --description=Adds a procedure to a tRPC API

bun

bunx nx g @aws/nx-plugin:ts#nx-generator --pluginProject=@aws/nx-plugin --name=ts#trpc-api#procedure --directory=trpc/procedure --description=Adds a procedure to a tRPC API

Puoi anche eseguire una prova per vedere quali file verrebbero modificati

pnpm

pnpm nx g @aws/nx-plugin:ts#nx-generator --pluginProject=@aws/nx-plugin --name=ts#trpc-api#procedure --directory=trpc/procedure --description=Adds a procedure to a tRPC API --dry-run

yarn

yarn nx g @aws/nx-plugin:ts#nx-generator --pluginProject=@aws/nx-plugin --name=ts#trpc-api#procedure --directory=trpc/procedure --description=Adds a procedure to a tRPC API --dry-run

npm

npx nx g @aws/nx-plugin:ts#nx-generator --pluginProject=@aws/nx-plugin --name=ts#trpc-api#procedure --directory=trpc/procedure --description=Adds a procedure to a tRPC API --dry-run

bun

bunx nx g @aws/nx-plugin:ts#nx-generator --pluginProject=@aws/nx-plugin --name=ts#trpc-api#procedure --directory=trpc/procedure --description=Adds a procedure to a tRPC API --dry-run

Noterai che sono stati generati i seguenti file:

• Directorypackages/nx-plugin/src/trpc/procedure

  • schema.json Definisce l’input per il generatore
  • schema.d.ts Un’interfaccia TypeScript che corrisponde allo schema
  • generator.ts Funzione eseguita da Nx come generatore
  • generator.spec.ts Test per il generatore
• Directorydocs/src/content/docs/guides/

  • trpc-procedure.mdx Documentazione per il generatore
• packages/nx-plugin/generators.json Aggiornato per includere il generatore

Aggiorniamo lo schema per aggiungere le proprietà necessarie al generatore:

schema.json

{
  "$schema": "https://json-schema.org/schema",
  "$id": "tRPCProcedure",
  "title": "Adds a procedure to a tRPC API",
  "type": "object",
  "properties": {
    "project": {
      "type": "string",
      "description": "tRPC API project",
      "x-prompt": "Select the tRPC API project to add the procedure to",
      "x-dropdown": "projects",
      "x-priority": "important"
    },
    "procedure": {
      "description": "The name of the new procedure",
      "type": "string",
      "x-prompt": "What would you like to call your new procedure?",
      "x-priority": "important",
    },
    "type": {
      "description": "The type of procedure to generate",
      "type": "string",
      "x-prompt": "What type of procedure would you like to generate?",
      "x-priority": "important",
      "default": "query",
      "enum": ["query", "mutation"]
    }
  },
  "required": ["project", "procedure"]
}

schema.d.ts

export interface TrpcProcedureSchema {
  project: string;
  procedure: string;
  type: 'query' | 'mutation';
}

Nota

Nota: al generatore viene fornito un Tree come input, insieme alle opzioni definite nello schema. Il Tree è essenzialmente un file system virtuale da cui possiamo leggere e scrivere per creare o aggiornare i file del progetto. Non vogliamo accedere direttamente al file system, poiché non vogliamo apportare modifiche se gli utenti eseguono il generatore in modalità “dry-run”.

Noterai che il generatore è già stato collegato in packages/nx-plugin/generators.json:

 ...
  "generators": {
    ...
    "ts#trpc-api#procedure": {
      "factory": "./src/trpc/procedure/generator",
      "schema": "./src/trpc/procedure/schema.json",
      "description": "Adds a procedure to a tRPC API"
    }
  },
...

Implementa il Generatore

Per aggiungere una procedura a un’API tRPC, dobbiamo fare due cose:

1. Creare un file TypeScript per la nuova procedura
2. Aggiungere la procedura al router

Crea la Nuova Procedura

Per creare il file TypeScript per la nuova procedura, useremo un’utility chiamata generateFiles. Utilizzando questa, possiamo definire un template EJS che possiamo renderizzare nel nostro generatore con variabili basate sulle opzioni selezionate dall’utente.

Per prima cosa, definiamo il template in packages/nx-plugin/src/trpc/procedure/files/procedures/__procedureNameKebabCase__.ts.template:

files/procedures/__procedureNameKebabCase__.ts.template

import { publicProcedure } from '../init.js';
import { z } from 'zod';

export const <%- procedureNameCamelCase %> = publicProcedure
  .input(z.object({
    // TODO: define input
  }))
  .output(z.object({
    // TODO: define output
  }))
  .<%- procedureType %>(async ({ input, ctx }) => {
    // TODO: implement!
    return {};
  });

Consiglio

Quando generateFiles elabora il template, sostituirà i riferimenti a __<variabile>__ nei nomi di file/directory con i valori forniti, rimuovendo anche .template dal nome del file.

Il contenuto del template è in EJS, dove le variabili sono referenziate usando la sintassi <% ... %>.

Nel template, abbiamo referenziato tre variabili:

• procedureNameCamelCase
• procedureNameKebabCase
• procedureType

Quindi dobbiamo assicurarci di passare queste a generateFiles, insieme alla directory in cui generare i file, ovvero la posizione dei file sorgente (cioè sourceRoot) per il progetto tRPC selezionato dall’utente come input per il generatore, che possiamo estrarre dalla configurazione del progetto.

Aggiorniamo il generatore per fare ciò:

procedure/generator.ts

import {
  generateFiles,
  joinPathFragments,
  readProjectConfiguration,
  Tree,
} from '@nx/devkit';
import { TrpcProcedureSchema } from './schema';
import { formatFilesInSubtree } from '../../utils/format';
import camelCase from 'lodash.camelcase';
import kebabCase from 'lodash.kebabcase';

export const trpcProcedureGenerator = async (
  tree: Tree,
  options: TrpcProcedureSchema,
) => {
  const projectConfig = readProjectConfiguration(tree, options.project);

  const procedureNameCamelCase = camelCase(options.procedure);
  const procedureNameKebabCase = kebabCase(options.procedure);

  generateFiles(
    tree,
    joinPathFragments(__dirname, 'files'),
    projectConfig.sourceRoot,
    {
      procedureNameCamelCase,
      procedureNameKebabCase,
      procedureType: options.type,
    },
  );

  await formatFilesInSubtree(tree);
};

export default trpcProcedureGenerator;

Consiglio

Abbiamo anche chiamato formatFilesInSubtree alla fine del generatore, che assicura che tutti i file creati o modificati siano formattati secondo le impostazioni prettier dell’utente.

Aggiungi la Procedura al Router

Successivamente, vogliamo che il generatore colleghi la nuova procedura al router. Questo significa leggere e modificare il codice sorgente dell’utente!

Usiamo la manipolazione dell’AST di TypeScript per aggiornare le parti rilevanti del file sorgente TypeScript. Ci sono alcuni helper chiamati replace e destructuredImport per semplificare questa operazione.

procedure/generator.ts

import {
  generateFiles,
  joinPathFragments,
  readProjectConfiguration,
  Tree,
} from '@nx/devkit';
import { TrpcProcedureSchema } from './schema';
import { formatFilesInSubtree } from '../../utils/format';
import camelCase from 'lodash.camelcase';
import kebabCase from 'lodash.kebabcase';
import { destructuredImport, replace } from '../../utils/ast';
import { factory, ObjectLiteralExpression } from 'typescript';

export const trpcProcedureGenerator = async (
  tree: Tree,
  options: TrpcProcedureSchema,
) => {
  const projectConfig = readProjectConfiguration(tree, options.project);

  const procedureNameCamelCase = camelCase(options.procedure);
  const procedureNameKebabCase = kebabCase(options.procedure);

  generateFiles(
    tree,
    joinPathFragments(__dirname, 'files'),
    projectConfig.sourceRoot,
    {
      procedureNameCamelCase,
      procedureNameKebabCase,
      procedureType: options.type,
    },
  );

  const routerPath = joinPathFragments(projectConfig.sourceRoot, 'router.ts');

  destructuredImport(
    tree,
    routerPath,
    [procedureNameCamelCase],
    `./procedures/${procedureNameKebabCase}.js`,
  );

  replace(
    tree,
    routerPath,
    'CallExpression[expression.name="router"] > ObjectLiteralExpression',
    (node) =>
      factory.createObjectLiteralExpression([
        ...(node as ObjectLiteralExpression).properties,
        factory.createShorthandPropertyAssignment(procedureNameCamelCase),
      ]),
  );

  await formatFilesInSubtree(tree);
};

export default trpcProcedureGenerator;

Consiglio

Nel frammento di codice sopra, replace usa un selettore tsquery per trovare l’argomento aggiunto alla funzione router.

Puoi usare il tsquery playground come strumento utile per testare diversi selettori.

Ora che abbiamo implementato il generatore, compiliamolo per assicurarci che sia disponibile per testarlo nel nostro progetto dungeon adventure.

pnpm nx run @aws/nx-plugin:compile

Testare il Generatore

Per testare il generatore, collegheremo il nostro Nx Plugin for AWS locale a una codebase esistente.

Crea un Progetto di Test con un’API tRPC

Nota

Se hai completato il tutorial dell’avventura nel dungeon, o hai già un altro workspace Nx esistente che utilizza un’API tRPC, puoi saltare questo passaggio.

In una directory separata, crea un nuovo workspace di test:

pnpm

npx create-nx-workspace@~21.0.3 trpc-generator-test --pm=pnpm --preset=@aws/nx-plugin --ci=skip

yarn

npx create-nx-workspace@~21.0.3 trpc-generator-test --pm=yarn --preset=@aws/nx-plugin --ci=skip

npm

npx create-nx-workspace@~21.0.3 trpc-generator-test --pm=npm --preset=@aws/nx-plugin --ci=skip

bun

npx create-nx-workspace@~21.0.3 trpc-generator-test --pm=bun --preset=@aws/nx-plugin --ci=skip

Quindi, generiamo un’API tRPC a cui aggiungere la procedura:

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#trpc-api
5. Compila i parametri richiesti
   • apiName: test-api
6. Clicca su Generate

CLI

pnpm

pnpm nx g @aws/nx-plugin:ts#trpc-api --apiName=test-api --no-interactive

yarn

yarn nx g @aws/nx-plugin:ts#trpc-api --apiName=test-api --no-interactive

npm

npx nx g @aws/nx-plugin:ts#trpc-api --apiName=test-api --no-interactive

bun

bunx nx g @aws/nx-plugin:ts#trpc-api --apiName=test-api --no-interactive

Puoi anche eseguire una prova per vedere quali file verrebbero modificati

pnpm

pnpm nx g @aws/nx-plugin:ts#trpc-api --apiName=test-api --no-interactive --dry-run

yarn

yarn nx g @aws/nx-plugin:ts#trpc-api --apiName=test-api --no-interactive --dry-run

npm

npx nx g @aws/nx-plugin:ts#trpc-api --apiName=test-api --no-interactive --dry-run

bun

bunx nx g @aws/nx-plugin:ts#trpc-api --apiName=test-api --no-interactive --dry-run

Collega il nostro Nx Plugin for AWS Locale

Nella tua codebase, colleghiamo il nostro @aws/nx-plugin locale:

pnpm

cd path/to/trpc-generator-test
pnpm link path/to/nx-plugin-for-aws/dist/packages/nx-plugin

yarn

cd path/to/trpc-generator-test
yarn link path/to/nx-plugin-for-aws/dist/packages/nx-plugin

npm

cd path/to/trpc-generator-test
npm link path/to/nx-plugin-for-aws/dist/packages/nx-plugin

bun

cd path/to/nx-plugin-for-aws/dist/packages/nx-plugin
bun link
cd path/to/trpc-generator-test
bun link @aws/nx-plugin

Nota

Nota sopra che abbiamo collegato il plugin compilato in dist/packages/nx-plugin anziché il codice sorgente.

Esegui il Nuovo Generatore

Proviamo il nuovo generatore:

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#trpc-api#procedure
5. Compila i parametri richiesti
6. Clicca su Generate

CLI

pnpm

pnpm nx g @aws/nx-plugin:ts#trpc-api#procedure

yarn

yarn nx g @aws/nx-plugin:ts#trpc-api#procedure

npm

npx nx g @aws/nx-plugin:ts#trpc-api#procedure

bun

bunx nx g @aws/nx-plugin:ts#trpc-api#procedure

Puoi anche eseguire una prova per vedere quali file verrebbero modificati

pnpm

pnpm nx g @aws/nx-plugin:ts#trpc-api#procedure --dry-run

yarn

yarn nx g @aws/nx-plugin:ts#trpc-api#procedure --dry-run

npm

npx nx g @aws/nx-plugin:ts#trpc-api#procedure --dry-run

bun

bunx nx g @aws/nx-plugin:ts#trpc-api#procedure --dry-run

Nota

Se non vedi il nuovo generatore nella lista in VSCode, potresti dover aggiornare lo workspace Nx:

pnpm

pnpm nx reset

yarn

yarn nx reset

npm

npx nx reset

bun

bunx nx reset

Se ha successo, dovremmo aver generato una nuova procedura e aggiunto la procedura al nostro router in router.ts.

Esercizi

Se sei arrivato fin qui e hai ancora del tempo per sperimentare con i generatori Nx, ecco alcuni suggerimenti di funzionalità da aggiungere al generatore di procedure:

1. Operazioni Annidate

Prova ad aggiornare il generatore per supportare router annidati:

• Accettando la notazione puntata per l’input procedure (es. games.query)
• Generando una procedura con un nome basato sulla notazione puntata invertita (es. queryGames)
• Aggiungendo il router annidato appropriato (o aggiornandolo se esiste già!)

2. Validazione

Il nostro generatore dovrebbe prevenire potenziali problemi, come un utente che seleziona un project che non è un’API tRPC. Dai un’occhiata al generatore api-connection per un esempio.

3. Test Unitari

Scrivi alcuni test unitari per il generatore. Sono abbastanza semplici da implementare e seguono generalmente il flusso:

1. Crea un workspace tree vuoto usando createTreeUsingTsSolutionSetup()
2. Aggiungi eventuali file che dovrebbero già esistere nel tree (es. project.json e src/router.ts per un backend tRPC)
3. Esegui il generatore sotto test
4. Verifica che le modifiche attese siano state apportate al tree

4. Test End-to-End

Attualmente, abbiamo un singolo “test di smoke” che esegue tutti i generatori e verifica che la build abbia successo. Questo dovrebbe essere aggiornato per includere il nuovo generatore.