License

Gestiona las licencias en todo tu espacio de trabajo: sincroniza archivos LICENSE y encabezados de código fuente para tu propio código (license.source), y verifica que cada dependencia cumpla con una lista de licencias permitidas (license.dependencies).

Uso

Ejecutar el Generador

CLI

pnpm

pnpm nx g @aws/nx-plugin:license

yarn

yarn nx g @aws/nx-plugin:license

npm

npx nx g @aws/nx-plugin:license

bun

bunx nx g @aws/nx-plugin:license

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

pnpm

pnpm nx g @aws/nx-plugin:license --dry-run

yarn

yarn nx g @aws/nx-plugin:license --dry-run

npm

npx nx g @aws/nx-plugin:license --dry-run

bun

bunx nx g @aws/nx-plugin:license --dry-run

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 - license
5. Complete los parámetros requeridos
6. Haga clic en Generate

Opciones

Parámetro	Tipo	Predeterminado	Descripción
license	Apache-2.0 | MIT | ASL	Apache-2.0	Identificador SPDX de licencia para la licencia elegida
copyrightHolder	string	Amazon.com, Inc. or its affiliates	El titular de los derechos de autor, incluido en el archivo LICENSE y en los encabezados de los archivos fuente por defecto.
dependencyCheck	boolean	true	Configura un target de verificación de licencias que falla cuando las dependencias declaran licencias fuera de la lista permitida configurada.
preferInstallDependencies	boolean	true	Si se prefiere instalar las dependencias después de que se ejecute el generador. Establecer en false para diferir la instalación al ejecutar múltiples generadores en lote (la instalación aún se ejecuta si es necesaria para que los generadores subsecuentes puedan calcular el grafo de proyectos de Nx); instalar una vez al final.

Salida del Generador

El generador creará o actualizará los siguientes archivos:

• nx.json El target lint está configurado para ejecutar el generador de sincronización de licencias y depende del target license-check
• aws-nx-plugin.config.mts Configuración para la sincronización de fuentes de licencia (license.source) y verificación de dependencias (license.dependencies)

Encabezados y Archivos de Licencia

El generador registra un generador de sincronización para ejecutarse como parte de tus targets lint, lo que garantiza que tus archivos fuente contengan los encabezados de licencia correctos, tus proyectos contengan archivos LICENSE, y los metadatos de licencia estén configurados en package.json y pyproject.toml.

Flujo de Trabajo

Cada vez que construyas tus proyectos (y se ejecute un target lint), el generador de sincronización de licencias se asegurará de que las licencias en tu proyecto coincidan con tu configuración. Si detecta que algo está desincronizado, recibirás un mensaje como este:

  NX   The workspace is out of sync

[@aws/nx-plugin:license#sync]: Project LICENSE files are out of sync:
- LICENSE
- packages/<my-project>LICENSE

Project package.json files are out of sync:
- package.json

Project pyproject.toml files are out of sync:
- pyproject.toml
- packages/<my-python-project>/pyproject.toml

License headers are out of sync in the following source files:
- packages/<my-project>/src/index.ts
- packages/<my-python-project>/main.py

This will result in an error in CI.

? 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

Selecciona Yes para sincronizar los cambios.

Revisar Cambios

Asegúrate de revisar los cambios que el generador de sincronización de licencias realiza en el control de versiones para garantizar que las tareas de compilación de integración continua no fallen debido a licencias desincronizadas.

Comportamiento de Sincronización

El generador de sincronización de licencias realiza tres tareas principales:

1. Sincronizar Encabezados de Licencia en Archivos Fuente

Cuando se ejecuta el generador de sincronización, se asegurará de que todos los archivos de código fuente en tu espacio de trabajo (según tu configuración) contengan el encabezado de licencia apropiado. El encabezado se escribe como el primer comentario de bloque o serie consecutiva de comentarios de línea en el archivo (además del shebang/hashbang si está presente en un archivo).

2. Sincronizar Archivos LICENSE

Cuando se ejecuta el generador de sincronización, se asegurará de que el archivo LICENSE raíz corresponda a tu licencia configurada, así como de garantizar que todos los subproyectos en tu espacio de trabajo también contengan el archivo LICENSE correcto.

3. Sincronizar información de licencias en archivos de proyecto

Cuando se ejecuta el generador de sincronización, se asegurará de que los campos license en los archivos package.json y pyproject.toml estén configurados con tu licencia configurada.

Configuración de Encabezados y Archivos

La configuración se define en el archivo aws-nx-plugin.config.mts en la raíz de tu espacio de trabajo.

SPDX y Titular de Derechos de Autor

Tu licencia elegida puede actualizarse en cualquier momento a través de la propiedad de configuración spdx:

aws-nx-plugin.config.mts

export default {
  license: {
    source: {
      spdx: 'MIT',
    },
  },
} satisfies AwsNxPluginConfig;

Cuando se ejecuta el generador de sincronización, todos los archivos LICENSE, package.json y pyproject.toml se actualizarán para reflejar la licencia configurada.

Además, puedes configurar el titular de los derechos de autor y el año de copyright, que se incluyen en algunos archivos LICENSE:

aws-nx-plugin.config.mts

export default {
  license: {
    source: {
      spdx: 'MIT',
      copyrightHolder: 'Amazon.com, Inc. or its affiliates',
      copyrightYear: 2025,
    },
  },
} satisfies AwsNxPluginConfig;

Contenido del Encabezado de Licencia

El contenido del encabezado de licencia se puede configurar de dos maneras:

1. Usando contenido en línea:

aws-nx-plugin.config.mts

export default {
  license: {
    source: {
      header: {
        content: {
          lines: [
            'Copyright: My Company, Incorporated.',
            'Licensed under the MIT License',
            'All rights reserved',
          ];
        }
        // ... format configuration
      }
    }
  }
} satisfies AwsNxPluginConfig;

2. Cargando desde un archivo:

aws-nx-plugin.config.mts

export default {
  license: {
    source: {
      header: {
        content: {
          filePath: 'license-header.txt'; // relative to workspace root
        }
        // ... format configuration
      }
    }
  }
} satisfies AwsNxPluginConfig;

Formato del Encabezado

Puedes especificar cómo deben formatearse los encabezados de licencia para diferentes tipos de archivo usando patrones glob. La configuración de formato admite comentarios de línea, comentarios de bloque o una combinación de ambos:

aws-nx-plugin.config.mts

export default {
  license: {
    source: {
      header: {
        content: {
          lines: ['Copyright notice here'],
        },
        format: {
          // Line comments
          '**/*.ts': {
            lineStart: '// ',
          },
          // Block comments
          '**/*.css': {
            blockStart: '/*',
            blockEnd: '*/',
          },
          // Block comments with line prefixes
          '**/*.java': {
            blockStart: '/*',
            lineStart: ' * ',
            blockEnd: ' */',
          },
          // Line comments with header/footer
          '**/*.py': {
            blockStart: '# ------------',
            lineStart: '# ',
            blockEnd: '# ------------',
          },
        },
      },
    },
  },
} satisfies AwsNxPluginConfig;

La configuración de formato admite:

• blockStart: Texto escrito antes del contenido de la licencia (por ejemplo, para iniciar un comentario de bloque)
• lineStart: Texto antepuesto a cada línea del contenido de la licencia
• lineEnd: Texto agregado al final de cada línea del contenido de la licencia
• blockEnd: Texto escrito después del contenido de la licencia (por ejemplo, para finalizar un comentario de bloque)

Sintaxis de Comentarios Personalizada

Para tipos de archivo que no son compatibles de forma nativa, puedes especificar una sintaxis de comentarios personalizada para indicarle al generador de sincronización cómo identificar encabezados de licencia existentes en estos tipos de archivo.

aws-nx-plugin.config.mts

export default {
  license: {
    source: {
      header: {
        content: {
          lines: ['My license header'],
        },
        format: {
          '**/*.xyz': {
            lineStart: '## ',
          },
        },
        commentSyntax: {
          xyz: {
            line: '##', // Define line comment syntax
          },
          abc: {
            block: {
              // Define block comment syntax
              start: '<!--',
              end: '-->',
            },
          },
        },
      },
    },
  },
} satisfies AwsNxPluginConfig;

Excluir Archivos de la Sincronización de Encabezados

Por defecto, en un repositorio git, todos los archivos .gitignore se respetan para garantizar que solo se sincronicen los archivos gestionados por control de versiones. En repositorios que no son git, todos los archivos se consideran a menos que se excluyan explícitamente en la configuración.

Puedes excluir archivos adicionales de la sincronización de encabezados de licencia usando patrones glob:

aws-nx-plugin.config.mts

export default {
  license: {
    source: {
      header: {
        content: {
          lines: ['My license header'],
        },
        format: {
          '**/*.ts': {
            lineStart: '// ',
          },
        },
        exclude: ['**/generated/**', '**/dist/**', 'some-specific-file.ts'],
      },
    },
  },
} satisfies AwsNxPluginConfig;

Excluir Proyectos de la Sincronización de Archivos

Todos los archivos LICENSE, archivos package.json y archivos pyproject.toml se sincronizan con la licencia configurada por defecto.

Puedes excluir proyectos o archivos específicos de la sincronización usando patrones glob:

aws-nx-plugin.config.mts

export default {
  license: {
    source: {
      files: {
        exclude: [
          // do not sync LICENSE file, package.json or pyproject.toml
          'packages/excluded-project',
          // do not sync LICENSE file, but sync package.json and/or pyproject.toml
          'apps/internal/LICENSE',
        ];
      }
    }
  }
} satisfies AwsNxPluginConfig;

Deshabilitar la Sincronización de Licencias

La sincronización de fuentes de licencia se habilita mediante la presencia de la clave license.source en tu configuración. Para deshabilitarla:

1. Elimina la sección license.source de tu configuración en aws-nx-plugin.config.mts (puedes mantener license.dependencies si aún deseas la verificación de licencias de dependencias)
2. Si también deseas eliminar completamente el generador de sincronización, elimina el generador @aws/nx-plugin:license#sync de targetDefaults.lint.syncGenerators

Para volver a habilitar la sincronización de licencias, simplemente ejecuta el generador license nuevamente.

Verificaciones de Licencias de Dependencias

El generador license también configura un target license-check que falla cuando una de las dependencias de tu proyecto (o cualquier dependencia transitiva) declara una licencia que no está en tu lista de permitidas.

Cómo se ejecuta

El generador escribe un target license-check en tu project.json raíz:

project.json

{
  "targets": {
    "license-check": {
      "executor": "@aws/nx-plugin:license-check",
      "cache": true,
      "inputs": [
        "{workspaceRoot}/pnpm-lock.yaml",
        "{workspaceRoot}/aws-nx-plugin.config.mts"
      ],
      "options": {}
    }
  }
}

Los inputs se calculan para tu espacio de trabajo: solo se incluyen los archivos de bloqueo que realmente están presentes, junto con aws-nx-plugin.config.mts, más un glob {workspaceRoot}/**/uv.lock cuando la verificación de dependencias de Python está habilitada (es decir, se configura un recolector de Python).

Puedes ejecutar la verificación directamente:

pnpm

pnpm nx license-check

yarn

yarn nx license-check

npm

npx nx license-check

bun

bunx nx license-check

Los resultados se almacenan en caché contra tus archivos de bloqueo y aws-nx-plugin.config.mts — las re-ejecuciones son instantáneas cuando nada ha cambiado.

Los recolectores determinan qué se escanea. El npmCollector usa license-checker-rseidelsohn, y el pythonCollector usa pip-licenses. Si no se encuentran dependencias instaladas, la verificación pasa sin nada que inspeccionar.

Ejecutar como parte de lint/build

La verificación de licencias de dependencias se ejecuta automáticamente cada vez que ejecutas lint o build en cualquier proyecto de tu espacio de trabajo. El generador license conecta el target lint de cada proyecto para que dependa del target license-check raíz, y los generadores de proyecto (ts#* y py#*) hacen lo mismo cuando se ejecutan — por lo que la verificación se conecta independientemente del orden en que se ejecuten los generadores.

Esto significa que no necesitas ejecutar la verificación explícitamente, aunque aún puedes hacerlo con el target license-check:

pnpm

pnpm nx license-check

yarn

yarn nx license-check

npm

npx nx license-check

bun

bunx nx license-check

La conexión es un dependsOn entre proyectos en el target lint de cada proyecto que apunta al target license-check raíz. Para omitir la verificación durante un lint o build, establece la variable de entorno LICENSE_DEPENDENCY_CHECK=skip:

pnpm

pnpm LICENSE_DEPENDENCY_CHECK=skip lint

yarn

yarn LICENSE_DEPENDENCY_CHECK=skip lint

npm

npm run LICENSE_DEPENDENCY_CHECK=skip lint

bun

bun LICENSE_DEPENDENCY_CHECK=skip lint

Configuración

Por defecto, la verificación usa un conjunto integrado de licencias permisivas comunes (MIT, Apache-2.0, BSD, ISC, etc.) exportado como DEFAULT_LICENSE_ALLOWLIST. Puedes extender o anular esto en tu configuración:

aws-nx-plugin.config.mts

import { AwsNxPluginConfig } from '@aws/nx-plugin';
import { DEFAULT_LICENSE_ALLOWLIST } from '@aws/nx-plugin/sdk/license';

export default {
  license: {
    // ...
    dependencies: {
      allow: [...DEFAULT_LICENSE_ALLOWLIST, { spdxId: 'LGPL-2.1-or-later', fullName: 'GNU Lesser General Public License v2.1 or later', aliases: [] }],
      exceptions: [
        { package: 'some-package', reason: 'Audited manually — ships MIT text without SPDX field' },
      ],
    },
  },
} satisfies AwsNxPluginConfig;

Ver la lista completa de licencias en DEFAULT_LICENSE_ALLOWLIST

Personalizar la lista de permitidas

Para restringir la lista de permitidas, reemplaza DEFAULT_LICENSE_ALLOWLIST con tu propio array. Para extenderla, expande el valor predeterminado y agrega entradas. Las entradas se comparan por id SPDX, nombre completo de licencia o cualquiera de los alias listados (sin distinción entre mayúsculas y minúsculas).

Excepciones por paquete

Usa exceptions para paquetes que fallan la verificación — ya sea porque su licencia no está en la lista de permitidas, o porque se envían sin metadatos de licencia detectables. El campo reason es obligatorio para que los revisores puedan ver por qué se otorgó la excepción.

exceptions: [
  {
    package: 'union',
    version: '0.5.0',
    reason: 'Package ships verbatim MIT text without declaring license',
  },
];

Los generadores que introducen dependencias con metadatos problemáticos (por ejemplo, el generador de servidor MCP) agregan automáticamente las excepciones requeridas a tu configuración cuando se ejecutan.

Recolectores

Los recolectores descubren dependencias y extraen metadatos de licencia. Los recolectores integrados son npmCollector() (escanea node_modules) y pythonCollector() (escanea entornos virtuales de Python). El generador de licencias configura npmCollector() por defecto y agrega pythonCollector() cuando hay proyectos de Python presentes.

Para implementar un recolector personalizado, cumple con la interfaz LicenseCollector:

import type { LicenseCollector } from '@aws/nx-plugin/sdk/license';

const myCollector = (): LicenseCollector => ({
  name: 'my-ecosystem',
  traceCommand: 'my-tool why <package>',
  async collect({ workspaceRoot }) {
    return [
      { name: 'some-dep', version: '1.0.0', rawLicense: 'MIT', ecosystem: 'my-ecosystem' },
    ];
  },
});

El hook onDependency

license.dependencies acepta un callback opcional onDependency que se invoca una vez por cada dependencia descubierta, independientemente de si pasa o falla la verificación. Recibe { package, spdx }, donde package es el nombre del paquete y spdx es la expresión de licencia SPDX resuelta. El spdx de una excepción tiene precedencia sobre la licencia declarada sin procesar, y spdx puede ser una cadena vacía si no se declaró ninguna licencia.

Esta es una forma práctica de imprimir todas las licencias en tu proyecto. Ejecuta el target license-check para ver la salida:

aws-nx-plugin.config.mts

import { AwsNxPluginConfig } from '@aws/nx-plugin';
import { DEFAULT_LICENSE_ALLOWLIST } from '@aws/nx-plugin/sdk/license';

export default {
  license: {
    dependencies: {
      allow: DEFAULT_LICENSE_ALLOWLIST,
      onDependency: ({ package: pkg, spdx }) => {
        console.log(`${pkg} - ${spdx}`);
      },
    },
  },
} satisfies AwsNxPluginConfig;

Deshabilitar las Verificaciones de Dependencias

La verificación de licencias de dependencias se habilita mediante la presencia de la clave license.dependencies en tu configuración.

Para deshabilitar las verificaciones para una sola ejecución, establece la variable de entorno LICENSE_DEPENDENCY_CHECK=skip:

pnpm

pnpm LICENSE_DEPENDENCY_CHECK=skip lint

yarn

yarn LICENSE_DEPENDENCY_CHECK=skip lint

npm

npm run LICENSE_DEPENDENCY_CHECK=skip lint

bun

bun LICENSE_DEPENDENCY_CHECK=skip lint

Para deshabilitar permanentemente, elimina la clave license.dependencies de tu configuración en aws-nx-plugin.config.mts. También puedes volver a ejecutar el generador license con --dependencyCheck=false para generar sin ella.