Proyectos de TypeScript

El generador de proyectos TypeScript permite crear bibliotecas o aplicaciones modernas con TypeScript configuradas con mejores prácticas como Módulos ECMAScript (ESM), referencias de proyecto de TypeScript, Vitest para ejecutar pruebas y ESLint para análisis estático.

Uso

Generar un proyecto TypeScript

Puedes generar un nuevo proyecto TypeScript 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#project
5. Complete los parámetros requeridos
6. Haga clic en Generate

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

Opciones

Parámetro	Tipo	Predeterminado	Descripción
name Requerido	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.

Salida del generador

El generador creará la siguiente estructura de proyecto en el directorio <directory>/<name>:

• Directorysrc Código fuente TypeScript

  • index.ts
• project.json Configuración del proyecto y objetivos de build
• tsconfig.json Configuración base de TypeScript para este proyecto (extiende tsconfig.base.json del workspace)
• tsconfig.lib.json Configuración TypeScript para tu biblioteca (código de ejecución o empaquetado)
• tsconfig.spec.json Configuración TypeScript para tus pruebas
• vite.config.ts Configuración para Vitest
• eslint.config.mjs Configuración para ESLint

Consejo

¡Observa que no se crea ningún archivo package.json para este proyecto! Puedes descubrir por qué abajo.

También notarás 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 TypeScript para tu proyecto para que pueda ser importado por otros proyectos
• tsconfig.json Se añade una referencia de proyecto TypeScript para tu proyecto

Escribiendo código TypeScript

Añade tu código TypeScript en el directorio src.

Sintaxis de importación ESM

Como tu proyecto TypeScript es un Módulo ES, asegúrate de escribir las sentencias de importación con la sintaxis ESM correcta, incluyendo explícitamente la extensión del archivo:

index.ts

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

Nota

Aunque usemos TypeScript y sayHello esté definido en hello.ts, usamos la extensión .js en la importación. Puedes leer más sobre esto aquí.

Exportar para otros proyectos TypeScript

El punto de entrada de tu proyecto TypeScript es src/index.ts. Puedes añadir exports aquí para cualquier elemento que quieras que otros proyectos puedan importar:

src/index.ts

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

Importar tu biblioteca en otros proyectos

Los alias de TypeScript para tu proyecto se configuran en el archivo tsconfig.base.json del workspace, permitiendo referenciar tu proyecto TypeScript desde otros proyectos:

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

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

Nota

Los alias para proyectos TypeScript comienzan con : en lugar del tradicional @, evitando posibles conflictos de nombres entre paquetes locales en tu workspace y paquetes remotos en NPM.

Cuando añadas una sentencia de importación para un nuevo proyecto en tu workspace por primera vez, es probable que veas un error en tu IDE similar a este:

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 ocurre porque no se ha configurado una referencia de proyecto.

Los proyectos TypeScript vienen configurados con el generador Nx TypeScript Sync, evitando que necesites configurar manualmente las referencias. Simplemente ejecuta el siguiente comando y Nx añadirá la configuración requerida:

pnpm

pnpm nx sync

yarn

yarn nx sync

npm

npx nx sync

bun

bunx nx sync

Después de esto, el error en tu IDE debería desaparecer y podrás usar tu biblioteca.

Consejo

También puedes simplemente construir tu proyecto y verás un mensaje como:

[@nx/js:typescript-sync]: Some TypeScript configuration files are missing project references to the projects they depend on or contain outdated project references.

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 permitir que Nx actualice tus referencias de proyecto.

Dependencias

Notarás que tu proyecto TypeScript no tiene archivo package.json, lo cual puede resultar inesperado si estás acostumbrado a monorepos TypeScript tradicionales.

Para añadir una dependencia a cualquier paquete TypeScript en tu monorepo, simplemente añádela al package.json en la raíz de tu workspace. Puedes hacerlo vía línea de comandos:

pnpm

pnpm add -w some-npm-package

yarn

yarn add some-npm-package

npm

npm install --legacy-peer-deps some-npm-package

bun

bun install some-npm-package

La dependencia estará disponible para cualquier proyecto TypeScript en tu workspace.

Código de ejecución

Cuando uses tu proyecto TypeScript como código de ejecución (por ejemplo como handler de una función AWS Lambda), se recomienda usar una herramienta como esbuild para empaquetar tu proyecto, ya que permite tree-shaking para incluir solo las dependencias usadas.

Puedes lograrlo añadiendo un objetivo como este en tu 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"
      }
    },
  },
}

Nota

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

Publicar en NPM

Si vas a publicar tu proyecto TypeScript en NPM, debes crear un archivo package.json para él.

Este debe declarar las dependencias que usa tu proyecto. Como en tiempo de build las dependencias se resuelven desde el package.json raíz, se recomienda configurar el plugin ESLint de NX para verificación de dependencias para asegurar que tu package.json publicado incluye todas las dependencias usadas.

Construcción

Tu proyecto TypeScript tiene un objetivo build (definido en project.json) que puedes ejecutar con:

pnpm

pnpm nx run <project-name>:build

yarn

yarn nx run <project-name>:build

npm

npx nx run <project-name>:build

bun

bunx nx run <project-name>:build

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

El objetivo build compilará, linteará y probará tu proyecto.

La salida del build se encuentra en la carpeta dist raíz de tu workspace, dentro de un directorio para tu paquete y objetivo, por ejemplo dist/packages/<my-library>/tsc

Pruebas

Vitest está configurado para probar tu proyecto.

Escribiendo pruebas

Las pruebas deben escribirse en archivos .spec.ts o .test.ts, ubicados junto al código en la carpeta src.

Ejemplo:

• Directorysrc

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

Vitest provee 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('debe saludar al llamador', () => {
    expect(sayHello('Darth Vader')).toBe('Hello, Darth Vader!');
  });

});

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

Ejecutando pruebas

Las pruebas se ejecutan como parte del objetivo build, pero también puedes ejecutarlas por separado con el objetivo test:

pnpm

pnpm nx run <project-name>:test

yarn

yarn nx run <project-name>:test

npm

npx nx run <project-name>:test

bun

bunx nx run <project-name>:test

Puedes ejecutar una prueba individual con el flag -t:

pnpm

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

yarn

yarn nx run <project-name>:test -t 'sayHello'

npm

npx nx run <project-name>:test -t 'sayHello'

bun

bunx nx run <project-name>:test -t 'sayHello'

Consejo

Si usas VSCode, recomendamos instalar la extensión Vitest Runner for VSCode that actually works para ejecutar, monitorear o depurar pruebas desde tu IDE.

Linting

Los proyectos TypeScript usan ESLint para linting junto con Prettier para formateo.

Recomendamos configurar ESLint en el archivo eslint.config.mjs raíz del workspace, ya que los cambios aplicarán a todos los proyectos y garantizarán consistencia.

De igual forma, puedes configurar Prettier en el archivo .prettierrc raíz.

Ejecutando el linter

Para ejecutar el linter y verificar tu proyecto, usa el objetivo lint:

pnpm

pnpm nx run <project-name>:lint

yarn

yarn nx run <project-name>:lint

npm

npx nx run <project-name>:lint

bun

bunx nx run <project-name>:lint

Corrigiendo problemas de lint

La mayoría de problemas de lint o formateo pueden corregirse automáticamente. Puedes indicar a ESLint que corrija los problemas ejecutando con el argumento --configuration=fix:

pnpm

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

yarn

yarn nx run <project-name>:lint --configuration=fix

npm

npx nx run <project-name>:lint --configuration=fix

bun

bunx nx run <project-name>:lint --configuration=fix

Para corregir todos los problemas en todos los paquetes de tu workspace, ejecuta:

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