Generador de Generadores de Nx

Agrega un Generador de Nx a un proyecto TypeScript para ayudarte a automatizar tareas repetitivas como la creación de componentes o la aplicación de estructuras de proyecto específicas.

Uso

Generar un generador

Puedes generar un generador de dos formas:

VSCode

1. Instale el Nx Console VSCode Plugin si aún no lo ha hecho
2. Abra la consola Nx en VSCode
3. Haga clic en Generate (UI) en la sección "Common Nx Commands"
4. Busque @aws/nx-plugin - ts#nx-generator
5. Complete los parámetros requeridos
6. Haga clic en Generate

CLI

pnpm

pnpm nx g @aws/nx-plugin:ts#nx-generator

yarn

yarn nx g @aws/nx-plugin:ts#nx-generator

npm

npx nx g @aws/nx-plugin:ts#nx-generator

bun

bunx nx g @aws/nx-plugin:ts#nx-generator

También puede realizar una ejecución en seco para ver qué archivos se cambiarían

pnpm

pnpm nx g @aws/nx-plugin:ts#nx-generator --dry-run

yarn

yarn nx g @aws/nx-plugin:ts#nx-generator --dry-run

npm

npx nx g @aws/nx-plugin:ts#nx-generator --dry-run

bun

bunx nx g @aws/nx-plugin:ts#nx-generator --dry-run

Configuración recomendada

Recomendamos usar el generador ts#nx-plugin como proyecto base para cualquier generador que crees, ya que también proporciona un servidor MCP que ayuda a la IA a utilizar tus generadores.

Opciones

Parámetro	Tipo	Predeterminado	Descripción
project Requerido	string	-	Proyecto TypeScript al que agregar el generador. Recomendamos usar el generador ts#nx-plugin para crearlo.
name Requerido	string	-	Nombre del generador
description	string	-	Una descripción de tu generador
directory	string	-	El directorio dentro de la carpeta de código fuente del proyecto del plugin donde agregar el generador (predeterminado: <name>)

Salida del generador

El generador creará los siguientes archivos en el project seleccionado:

• Directoriosrc/<nombre>/

  • schema.json Esquema para la entrada del generador
  • schema.d.ts Tipos TypeScript para tu esquema
  • generator.ts Implementación base del generador
  • generator.spec.ts Pruebas para tu generador
  • README.md Documentación del generador
• generators.json Configuración de Nx para definir tus generadores
• package.json Creado o actualizado para agregar entrada “generators”
• tsconfig.json Actualizado para usar CommonJS

Modificación del proyecto

Este generador actualizará el project seleccionado para usar CommonJS, ya que los generadores de Nx actualmente solo soportan CommonJS (consulta este issue de GitHub para soporte ESM).

Generadores locales

Proyecto de plugin dedicado

Recomendamos generar primero un proyecto TypeScript dedicado para todos tus generadores usando el generador ts#nx-plugin. Por ejemplo:

VSCode

1. Instale el Nx Console VSCode Plugin si aún no lo ha hecho
2. Abra la consola Nx en VSCode
3. Haga clic en Generate (UI) en la sección "Common Nx Commands"
4. Busque @aws/nx-plugin - ts#nx-plugin
5. Complete los parámetros requeridos
   • name: nx-plugin
   • directory: tools
6. Haga clic en Generate

CLI

pnpm

pnpm nx g @aws/nx-plugin:ts#nx-plugin --name=nx-plugin --directory=tools

yarn

yarn nx g @aws/nx-plugin:ts#nx-plugin --name=nx-plugin --directory=tools

npm

npx nx g @aws/nx-plugin:ts#nx-plugin --name=nx-plugin --directory=tools

bun

bunx nx g @aws/nx-plugin:ts#nx-plugin --name=nx-plugin --directory=tools

También puede realizar una ejecución en seco para ver qué archivos se cambiarían

pnpm

pnpm nx g @aws/nx-plugin:ts#nx-plugin --name=nx-plugin --directory=tools --dry-run

yarn

yarn nx g @aws/nx-plugin:ts#nx-plugin --name=nx-plugin --directory=tools --dry-run

npm

npx nx g @aws/nx-plugin:ts#nx-plugin --name=nx-plugin --directory=tools --dry-run

bun

bunx nx g @aws/nx-plugin:ts#nx-plugin --name=nx-plugin --directory=tools --dry-run

Selecciona tu proyecto local nx-plugin al ejecutar el generador ts#nx-generator, y especifica un nombre junto con directorio y descripción opcionales.

Definir el esquema

El archivo schema.json define las opciones que acepta tu generador. Sigue el formato JSON Schema con extensiones específicas de Nx.

Estructura básica

Un archivo schema.json tiene la siguiente estructura básica:

{
  "$schema": "https://json-schema.org/schema",
  "$id": "YourGeneratorName",
  "title": "Your Generator Title",
  "description": "Description of what your generator does",
  "type": "object",
  "properties": {
    // Tus opciones del generador van aquí
  },
  "required": ["requiredOption1", "requiredOption2"]
}

Ejemplo simple

Aquí un ejemplo simple con algunas opciones básicas:

{
  "$schema": "https://json-schema.org/schema",
  "$id": "ComponentGenerator",
  "title": "Create a Component",
  "description": "Crea un nuevo componente React",
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "Nombre del componente",
      "x-priority": "important"
    },
    "directory": {
      "type": "string",
      "description": "Directorio donde se creará el componente",
      "default": "src/components"
    },
    "withTests": {
      "type": "boolean",
      "description": "Generar archivos de prueba",
      "default": true
    }
  },
  "required": ["name"]
}

Prompts interactivos (CLI)

Puedes personalizar los prompts mostrados al ejecutar tu generador vía CLI agregando la propiedad x-prompt:

"name": {
  "type": "string",
  "description": "Nombre del componente",
  "x-prompt": "¿Cuál es el nombre de tu componente?"
}

Para opciones booleanas, puedes usar un prompt sí/no:

"withTests": {
  "type": "boolean",
  "description": "Generar archivos de prueba",
  "x-prompt": "¿Deseas generar archivos de prueba?"
}

Selecciones en dropdown

Para opciones con un conjunto fijo de opciones, usa enum para que los usuarios puedan seleccionar:

"style": {
  "type": "string",
  "description": "Enfoque de estilos a usar",
  "enum": ["css", "scss", "styled-components", "none"],
  "default": "css"
}

Dropdown de selección de proyectos

Un patrón común es permitir seleccionar entre proyectos existentes:

"project": {
  "type": "string",
  "description": "Proyecto donde agregar el componente",
  "x-prompt": "¿A qué proyecto deseas agregar el componente?",
  "x-dropdown": "projects"
}

La propiedad x-dropdown: "projects" indica a Nx poblar el dropdown con todos los proyectos del workspace.

Argumentos posicionales

Puedes configurar opciones para recibirse como argumentos posicionales:

"name": {
  "type": "string",
  "description": "Nombre del componente",
  "x-priority": "important",
  "$default": {
    "$source": "argv",
    "index": 0
  }
}

Esto permite ejecutar el generador como nx g your-generator mi-componente en lugar de nx g your-generator --name=mi-componente.

Establecer prioridades

Usa la propiedad x-priority para indicar opciones importantes:

"name": {
  "type": "string",
  "description": "Nombre del componente",
  "x-priority": "important"
}

Las prioridades pueden ser "important" o "internal". Esto ayuda a Nx a ordenar propiedades en la extensión VSCode y CLI.

Valores predeterminados

Puedes proveer valores por defecto:

"directory": {
  "type": "string",
  "description": "Directorio para el componente",
  "default": "src/components"
}

Más información

Para más detalles sobre esquemas, consulta la documentación de Opciones de Generadores Nx.

Tipos TypeScript con schema.d.ts

Junto con schema.json, el generador crea un archivo schema.d.ts con tipos TypeScript:

export interface YourGeneratorSchema {
  name: string;
  directory?: string;
  withTests?: boolean;
}

Esta interfaz se usa en la implementación para seguridad de tipos:

import { YourGeneratorSchema } from './schema';

export default async function (tree: Tree, options: YourGeneratorSchema) {
  // TypeScript conoce los tipos de las opciones
  const { name, directory = 'src/components', withTests = true } = options;
  // ...
}

Cambios de esquema

Al modificar schema.json, debes actualizar schema.d.ts para que coincidan:

• Agregar/eliminar propiedades
• Cambiar tipos
• Hacer propiedades requeridas/opcionales (usa ? para opcionales)

La interfaz TypeScript debe reflejar fielmente el esquema JSON.

Implementar un generador

Tras crear el generador, puedes escribir su implementación en generator.ts.

Un generador es una función que muta un sistema de archivos virtual (Tree). Los cambios se escriben al disco al finalizar, a menos que se ejecute en modo “dry-run”. Un generador vacío:

export const myGenerator = async (tree: Tree, options: MyGeneratorSchema) => {
  // Usa el tree para aplicar cambios
};

export default myGenerator;

Operaciones comunes en generadores:

Leer y escribir archivos

// Leer archivo
const content = tree.read('ruta/al/archivo.ts', 'utf-8');

// Escribir archivo
tree.write('ruta/nuevo-archivo.ts', 'export const hola = "mundo";');

// Verificar existencia
if (tree.exists('ruta/al/archivo.ts')) {
  // Hacer algo
}

Generar archivos desde plantillas

Usa generateFiles de @nx/devkit con plantillas EJS:

import { generateFiles, joinPathFragments } from '@nx/devkit';

generateFiles(
  tree,
  joinPathFragments(__dirname, 'files'), // Directorio de plantillas
  'ruta/de/salida', // Directorio de salida
  {
    name: options.name,
    nameCamelCase: camelCase(options.name),
    nameKebabCase: kebabCase(options.name),
  },
);

Transformaciones de código con GritQL

Puedes usar GritQL para buscar y transformar código fuente de forma declarativa en tus generadores. GritQL soporta múltiples lenguajes incluyendo TypeScript, JavaScript, Python, HCL (Terraform) y más, permitiéndote usar la misma sintaxis de patrones en toda tu stack.

El Plugin Nx para AWS expone dos helpers:

• applyGritQL(tree, filePath, pattern) — aplica un patrón de reescritura GritQL a un archivo y retorna Promise<boolean> indicando si se realizaron cambios
• matchGritQL(tree, filePath, pattern) — verifica si un patrón GritQL coincide en algún lugar del archivo y retorna Promise<boolean>

import { applyGritQL, matchGritQL } from '@aws/nx-plugin/sdk/utils/ast';

// Reemplazar una llamada de función
await applyGritQL(
  tree,
  'src/app.ts',
  '`console.log($msg)` => `logger.info($msg)`',
);

// Agregar un elemento a un array solo si no está presente
await applyGritQL(
  tree,
  'src/plugins.ts',
  '`plugins: [$items]` => `plugins: [$items, myPlugin()]` where { $items <: not contains `myPlugin` }',
);

// Verificar si existe un patrón antes de hacer cambios
if (!(await matchGritQL(tree, filePath, '`import { Auth } from "./auth"`'))) {
  // Agregar el import
}

Los patrones GritQL también funcionan en archivos no-TypeScript. Prefija tu patrón con language <name> para apuntar a otros lenguajes:

// Python: reemplazar sentencias print con llamadas de logging
await applyGritQL(
  tree,
  'src/handler.py',
  'language python\n`print($msg)` => `logger.info($msg)`',
);

Los patrones GritQL usan fragmentos de código delimitados por backticks con $metavariables como comodines. Usa => para reescrituras y cláusulas where para condiciones.

Playground de GritQL

Puedes probar patrones GritQL en el Playground de GritQL, o instalar la CLI de GritQL localmente para probar patrones contra tus archivos:

npm install -g @getgrit/cli
grit apply '`console.log($msg)` => `logger.info($msg)`' --dry-run

Agentes de codificación IA

Si usas un agente de codificación IA para ayudar a escribir generadores, agrega el servidor MCP Context7 para darle documentación actualizada. Pídele que busque gritql y docs.grit.io para referencia de sintaxis de patrones GritQL, y proporciona acceso a la CLI de GritQL para que pueda probar patrones directamente.

Agregar dependencias

import { addDependenciesToPackageJson } from '@nx/devkit';

addDependenciesToPackageJson(
  tree,
  { 'nueva-dependencia': '^1.0.0' },
  { 'nueva-dev-dependencia': '^2.0.0' },
);

Dependencias de paquete

Para instalar dependencias después de generarlas:

import { installPackagesTask } from '@nx/devkit';

return () => {
  installPackagesTask(tree);
};

Formatear archivos

import { formatFilesInSubtree } from '@aws/nx-plugin/sdk/utils/format';

await formatFilesInSubtree(tree, 'ruta/opcional');

Leer y actualizar JSON

import { readJson, updateJson } from '@nx/devkit';

// Leer JSON
const packageJson = readJson(tree, 'package.json');

// Actualizar JSON
updateJson(tree, 'tsconfig.json', (json) => {
  json.compilerOptions.strict = true;
  return json;
});

Extender generadores del Plugin Nx para AWS

Importa y extiende generadores existentes:

import { tsProjectGenerator } from '@aws/nx-plugin/sdk/ts';

export const myGenerator = async (tree: Tree, schema: MyGeneratorSchema) => {
  const callback = await tsProjectGenerator(tree, { ... });
  // Extiende aquí
  return callback;
};

Generadores OpenAPI

Puedes usar generadores para clientes TypeScript:

import { openApiTsClientGenerator } from '@aws/nx-plugin/sdk/open-api';

export const myGenerator = async (tree: Tree, schema: MyGeneratorSchema) => {
  await openApiTsClientGenerator(tree, { ... });
  // Agregar archivos
};

También puedes generar datos desde especificaciones OpenAPI:

import { buildOpenApiCodeGenerationData } from '@aws/nx-plugin/sdk/open-api.js';

export const myGenerator = async (tree: Tree, schema: MyGeneratorSchema) => {
  const data = await buildOpenApiCodeGenerationData(tree, 'ruta/espec.json');
  generateFiles(tree, __dirname + '/files', 'ruta/salida', data);
};

Ejemplo de plantilla EJS:

files/my-operations.ts.template

export const myOperationNames = [
<%_ allOperations.forEach((op) => { _%>
  '<%- op.name %>',
<%_ }); _%>
];

Consulta el repositorio en GitHub para ejemplos complejos.

Ejecutar tu generador

Ejecuta tu generador de dos formas:

VSCode

1. Instale el Nx Console VSCode Plugin si aún no lo ha hecho
2. Abra la consola Nx en VSCode
3. Haga clic en Generate (UI) en la sección "Common Nx Commands"
4. Busque @my-project/nx-plugin - my-generator
5. Complete los parámetros requeridos
6. Haga clic en Generate

CLI

pnpm

pnpm nx g @my-project/nx-plugin:my-generator

yarn

yarn nx g @my-project/nx-plugin:my-generator

npm

npx nx g @my-project/nx-plugin:my-generator

bun

bunx nx g @my-project/nx-plugin:my-generator

También puede realizar una ejecución en seco para ver qué archivos se cambiarían

pnpm

pnpm nx g @my-project/nx-plugin:my-generator --dry-run

yarn

yarn nx g @my-project/nx-plugin:my-generator --dry-run

npm

npx nx g @my-project/nx-plugin:my-generator --dry-run

bun

bunx nx g @my-project/nx-plugin:my-generator --dry-run

El generador no aparece

Si no ves tu generador en la UI del plugin VSCode, actualiza tu workspace Nx con:

pnpm

pnpm nx reset

yarn

yarn nx reset

npm

npx nx reset

bun

bunx nx reset

Probar tu generador

Pruebas unitarias típicas:

import { createTreeWithEmptyWorkspace } from '@nx/devkit/testing';
import { yourGenerator } from './generator';

describe('tu generador', () => {
  let tree;

  beforeEach(() => {
    tree = createTreeWithEmptyWorkspace();
    tree.write('project.json', JSON.stringify({ name: 'test-project' }));
  });

  it('debe generar archivos esperados', async () => {
    await yourGenerator(tree, { name: 'test' });
    expect(tree.exists('src/test/file.ts')).toBeTruthy();
    expect(tree.read('src/test/file.ts', 'utf-8')).toMatchSnapshot();
  });

  it('debe manejar errores', async () => {
    await expect(yourGenerator(tree, { name: 'invalido' }))
      .rejects.toThrow('Mensaje de error esperado');
  });
});

Puntos clave:

• Usa createTreeWithEmptyWorkspace()
• Prueba creación y actualización de archivos
• Usa snapshots para contenido complejo
• Prueba condiciones de error

Contribuir generadores a @aws/nx-plugin

Usa ts#nx-generator para crear generadores dentro de @aws/nx-plugin.

Al ejecutarlo en nuestro repositorio, genera:

• Directoriopackages/nx-plugin/src/<nombre>/

  • schema.json
  • schema.d.ts
  • generator.ts
  • generator.spec.ts
• Directoriodocs/src/content/docs/guides/

  • <nombre>.mdx
• packages/nx-plugin/generators.json Actualizado

Contribuir generadores

Para una guía detallada sobre contribuir al Plugin Nx para AWS, consulta el tutorial aquí.