Proyectos TypeScript

El generador de proyectos TypeScript se puede utilizar para crear una biblioteca o aplicación moderna de TypeScript configurada con mejores prácticas como ECMAScript Modules (ESM), referencias de proyecto de TypeScript, Vitest para ejecutar pruebas y Biome para linting y formateo.

Uso

Generar un Proyecto TypeScript

Puedes generar un nuevo proyecto TypeScript de dos maneras:

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

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

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

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

Opciones

Parámetro	Tipo	Predeterminado	Descripción
name Requerido	string	-	Nombre del proyecto TypeScript
directory	string	packages	Directorio padre donde se coloca la biblioteca.
subDirectory	string	-	El subdirectorio donde se coloca la biblioteca. Por defecto es el nombre de la biblioteca.
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á la siguiente estructura de proyecto en el directorio <directory>/<name>:

• Directoriosrc Código fuente TypeScript

  • index.ts
• package.json Manifiesto del proyecto que define el nombre del paquete y las dependencias del proyecto
• project.json Configuración del proyecto y objetivos de compilación
• tsconfig.json Configuración base de TypeScript para este proyecto (extiende tsconfig.base.json de la raíz del workspace)
• tsconfig.lib.json Configuración de TypeScript para tu biblioteca (tu código fuente de runtime o empaquetado)
• tsconfig.spec.json Configuración de TypeScript para tus pruebas
• vitest.config.mts Configuración para Vitest

package.json del Proyecto

El package.json del proyecto comienza siendo mínimo. A medida que agregues dependencias de runtime, se declaran aquí (las herramientas compartidas de compilación/prueba permanecen en la raíz del workspace) — puedes obtener más información abajo.

También notarás algunos cambios en los siguientes archivos en la raíz de tu workspace:

• nx.json La configuración de Nx se actualiza para configurar el plugin @nx/js/typescript para tu proyecto
• tsconfig.base.json se configura un alias de TypeScript para tu proyecto para que pueda ser importado por otros proyectos en tu workspace
• tsconfig.json se agrega una referencia de proyecto TypeScript para tu proyecto

Escribir Código Fuente TypeScript

Agrega tu código TypeScript en el directorio src.

Sintaxis de Importación ESM

Dado que tu proyecto TypeScript es un Módulo ES, asegúrate de escribir tus declaraciones de importación con la sintaxis ESM correcta, haciendo referencia explícita a la extensión del archivo:

index.ts

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

Referencias de TypeScript

Aunque estamos usando TypeScript, y sayHello está definido en hello.ts, usamos la extensión de archivo .js en nuestra importación. Puedes leer más sobre esto aquí.

Exportar para Otros Proyectos TypeScript

El punto de entrada para tu proyecto TypeScript es src/index.ts. Puedes agregar exportaciones aquí para cualquier cosa que desees que otros proyectos puedan importar:

src/index.ts

export { sayHello } from './hello.js';
export * from './algorithms/index.js';

Importar el Código de tu Biblioteca en Otros Proyectos

Los alias de TypeScript para tu proyecto están configurados en el tsconfig.base.json de tu workspace, lo que te permite hacer referencia a tu proyecto TypeScript desde otros proyectos TypeScript:

packages/my-other-project/src/index.ts

import { sayHello } from '@my-scope/my-library';

Cuando agregues una declaración de importación para un nuevo proyecto en tu workspace por primera vez, probablemente verás un error en tu IDE similar al siguiente:

Error de importación

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)

Esto se debe a que aún no se ha configurado una referencia de proyecto, y el proyecto importado aún no se ha declarado como una dependencia del workspace en el package.json de tu proyecto.

Tu workspace está configurado con generadores de sincronización que gestionan ambos por ti, por lo que no necesitas configurarlos manualmente. Simplemente ejecuta el siguiente comando y Nx agregará la configuración requerida:

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!

El generador de sincronización de TypeScript de Nx agrega la referencia de proyecto, y el generador ts#sync del plugin declara el proyecto importado en el package.json de tu proyecto (workspace:* donde el gestor de paquetes soporta el protocolo workspace, * en npm y yarn classic), por lo que el gestor de paquetes enlaza el proyecto local en la instalación. Después de esto, el error en tu IDE debería desaparecer y estarás listo para usar tu biblioteca.

Atajo de Compilación

También puedes simplemente compilar tu proyecto — los generadores de sincronización se ejecutan primero y se te pedirá que apliques cualquier cambio pendiente:

 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

Selecciona Yes para permitir que Nx sincronice tu workspace.

Mantener los Alias de Ruta Sincronizados

Si agregas entradas personalizadas de compilerOptions.paths en el tsconfig.json de un proyecto, TypeScript deja de heredar los alias del workspace definidos en tsconfig.base.json. El generador oculto ts#sync se ejecuta antes del objetivo compile (configurado en nx.json) para copiar cualquier alias base faltante en los archivos tsconfig.json, tsconfig.lib.json y tsconfig.app.json que ya declaran paths. Para optar por no participar, elimina @aws/nx-plugin:ts#sync de targetDefaults.compile.syncGenerators en nx.json.

Dependencias

Cada proyecto TypeScript declara sus dependencias de runtime de terceros en su propio package.json. Las herramientas de compilación y prueba compartidas entre proyectos se definen en el package.json raíz.

Para agregar una dependencia de runtime a un proyecto, instálala en ese proyecto:

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

También puedes ejecutar el comando simple add/install de tu gestor de paquetes desde dentro del directorio del proyecto.

Para agregar una herramienta de desarrollo compartida, instálala en la raíz 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 regla de lint noUndeclaredDependencies de Biome garantiza que el código fuente de un proyecto solo importe paquetes declarados en su propio package.json. Los archivos de configuración, scripts de compilación y pruebas están exentos, por lo que las herramientas compartidas pueden permanecer en la raíz.

Catálogos

Para gestores de paquetes que soportan catálogos (pnpm, yarn y bun), los generadores registran cada versión en el catálogo y la referencian con el protocolo catalog: (ej. "zod": "catalog:"), por lo que el catálogo es la única fuente de verdad para las versiones independientemente de qué proyecto declare la dependencia. Esto te ayuda a seguir una política de versión única, evitando conflictos de tipos y múltiples copias de paquetes en los bundles de despliegue.

Cuando agregues una nueva dependencia tú mismo, mantenla también en el catálogo:

pnpm

El workspace establece catalogMode: strict, por lo que pnpm add registra la versión en el catálogo y la referencia automáticamente — sin pasos adicionales.

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

yarn

El protocolo catalog: de yarn solo referencia una entrada de catálogo existente — no puede crear una — así que registra la versión primero.

1. Agrega la versión bajo catalog en .yarnrc.yml:

   .yarnrc.yml

   catalog:
     some-npm-package: ^1.0.0

2. Refiérela desde el proyecto:

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

bun

El protocolo catalog: de bun solo referencia una entrada de catálogo existente — no puede crear una — así que registra la versión primero.

1. Agrega la versión bajo catalog en el package.json raíz:

   package.json

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

2. Refiérela desde el proyecto:

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

Alinear versiones en npm

npm no tiene una función de catálogo, por lo que las versiones se declaran directamente en cada package.json. Para mantenerlas consistentes entre proyectos, recomendamos syncpack (npx syncpack lint).

Optar por no usar catálogos

Los catálogos están habilitados por defecto. Para desactivarlos, crea tu 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

O configúralo en aws-nx-plugin.config.mts en cualquier momento:

aws-nx-plugin.config.mts

export default {
  packageManager: {
    catalogs: false,
  },
} satisfies AwsNxPluginConfig;

Con los catálogos deshabilitados, los generadores escriben las versiones de dependencias directamente en el package.json de cada proyecto, y mantener las versiones alineadas entre proyectos es tu responsabilidad.

Declarar todas las dependencias en la raíz

Si prefieres declarar cada dependencia solo en el package.json raíz (sin declaraciones de dependencias por proyecto), desactiva la regla de lint en el biome.json del workspace:

biome.json

{
  "linter": {
    "rules": {
      "correctness": {
        "noUndeclaredDependencies": "off"
      }
    }
  }
}

Los proyectos resuelven los paquetes instalados en la raíz en tiempo de compilación, por lo que todo sigue compilándose — renuncias a los manifiestos por proyecto como un registro preciso de las dependencias de cada proyecto (lo cual importa si luego publicas un proyecto o divides el repositorio).

Código de Runtime

Cuando uses tu proyecto TypeScript como código de runtime (por ejemplo, como el handler para una función AWS Lambda), se recomienda que uses una herramienta como Rolldown para empaquetar tu proyecto, ya que esto puede hacer tree-shaking para asegurar que solo se incluyan las dependencias que tu proyecto realmente referencia.

Puedes lograr esto agregando un objetivo como el siguiente a tu archivo project.json:

{
  ...
  "targets": {
    ...
    "bundle": {
      "cache": true,
      "executor": "nx:run-commands",
      "outputs": ["{workspaceRoot}/dist/packages/my-library/bundle"],
      "options": {
        "command": "rolldown -c rolldown.config.ts"
      }
    },
  },
}

Y agregando el archivo rolldown.config.ts de la siguiente manera:

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',
      codeSplitting: false,
    },
  },
]);

Configuración del Bundle

Ten en cuenta que en el objetivo anterior, elegimos src/index.ts como nuestro punto de entrada para el bundle, lo que significa que el código exportado desde este archivo se incluirá en el bundle, junto con todas sus dependencias.

Funciones Lambda

Si estás construyendo una función AWS Lambda, consulta el generador ts#lambda-function ya que este configura el empaquetado por ti, además de generar infraestructura y agregar observabilidad y seguridad de tipos.

Compilación

Tu proyecto TypeScript está configurado con un objetivo build (definido en project.json), que puedes ejecutar mediante:

pnpm

pnpm nx build <project-name>

yarn

yarn nx build <project-name>

npm

npx nx build <project-name>

bun

bunx nx build <project-name>

Donde <project-name> es el nombre completamente calificado de tu proyecto.

El objetivo build compilará, hará lint y probará tu proyecto.

La salida de compilación se puede encontrar en la carpeta dist raíz en tu workspace, dentro de un directorio para tu paquete y objetivo, por ejemplo dist/packages/<my-library>/tsc

Para compilar todos los proyectos en tu workspace, ejecuta:

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

O usa el comando abreviado:

pnpm

pnpm build

yarn

yarn build

npm

npm run build

bun

bun build

Pruebas

Vitest está configurado para probar tu proyecto.

Escribir Pruebas

Las pruebas deben escribirse en archivos .spec.ts o .test.ts, co-ubicados en la carpeta src de tu proyecto.

Por ejemplo:

• Directoriosrc

  • hello.ts Código fuente de la biblioteca
  • hello.spec.ts Pruebas para hello.ts

Vitest proporciona sintaxis similar a Jest para definir pruebas, con utilidades como describe, it, test y expect.

hello.spec.ts

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

describe('sayHello', () => {

  it('should greet the caller', () => {
    expect(sayHello('Darth Vader')).toBe('Hello, Darth Vader!');
  });

});

Para más detalles sobre cómo escribir pruebas, y características como simular dependencias, consulta la documentación de Vitest

Ejecutar Pruebas

Las pruebas se ejecutarán como parte del objetivo build para tu proyecto, pero también puedes ejecutarlas por separado ejecutando el objetivo 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>

Puedes ejecutar una prueba individual o un conjunto de pruebas usando la bandera -t de Vitest. Pásala después de un separador -- para que Nx la reenvíe a Vitest en lugar de consumirla como su propia opción --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'

Integración con VSCode

Si eres usuario de VSCode, recomendamos instalar la extensión Vitest Runner for VSCode that actually works, que te permite ejecutar, observar o depurar pruebas desde tu IDE.

Linting

Los proyectos TypeScript usan Biome para linting y formateo. Biome está configurado en el archivo biome.json de la raíz del workspace — los cambios a este se aplican a todos los proyectos TypeScript en tu workspace y aseguran consistencia.

Ejecutar el Linter

Para invocar el linter para verificar tu proyecto, puedes ejecutar el objetivo 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>

Corregir Problemas de Lint

La mayoría de los problemas de linting o formateo se pueden corregir automáticamente ejecutando con el argumento --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

De manera similar, si deseas corregir todos los problemas de lint en todos los paquetes de tu workspace, puedes ejecutar:

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 Abreviado

Este tiene un comando abreviado desde la raíz de tu workspace:

pnpm

pnpm lint

yarn

yarn lint

npm

npm run lint

bun

bun lint

Omitir Problemas de Lint

Para evitar que los problemas de linting te ralenticen durante el desarrollo (particularmente si tienes problemas no auto-corregibles en tu proyecto), puedes ejecutar una compilación con la configuración 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

Esto omite el objetivo lint por completo durante la compilación.

Comando Abreviado

Este tiene un comando abreviado desde la raíz de tu workspace:

pnpm

pnpm build:skip-lint

yarn

yarn build:skip-lint

npm

npm run build:skip-lint

bun

bun build:skip-lint