Proyectos de TypeScript

El generador de proyectos TypeScript se puede utilizar para crear una biblioteca o aplicación moderna TypeScript configurada 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 de 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 compilación
• 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 en tiempo 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 permitiendo su importación desde 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 tus sentencias de importación con la sintaxis ESM correcta, referenciando explícitamente la extensión del archivo:

index.ts

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

Nota

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

Exportando 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';

Importando tu biblioteca en otros proyectos

Los alias de TypeScript para tu proyecto están configurados en el tsconfig.base.json del workspace, permitiéndote 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, probablemente verás 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 de sincronización de TypeScript de Nx, 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 estarás listo para 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 ser inesperado si estás acostumbrado a monorepos TypeScript tradicionales.

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

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á entonces disponible para cualquier proyecto TypeScript en tu workspace.

Código en tiempo de ejecución

Cuando uses tu proyecto TypeScript como código en tiempo de ejecución (por ejemplo como handler para una función AWS Lambda), se recomienda usar una herramienta como Rolldown para empaquetar tu proyecto, ya que puede realizar tree-shake para incluir solo las dependencias realmente usadas.

Puedes lograr esto añadiendo un objetivo como el siguiente en 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 añadiendo el archivo rolldown.config.ts de la siguiente forma:

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',
      inlineDynamicImports: true,
    },
  },
]);

Nota

Nota que en el objetivo anterior elegimos src/index.ts como 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.

Consejo

Si estás construyendo una función AWS Lambda, revisa el generador ts#lambda-function ya que configura el empaquetado automáticamente, además de generar infraestructura y añadir observabilidad y type-safety.

Publicación 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 tu proyecto utiliza. Dado que en tiempo de compilación tu proyecto resuelve dependencias instaladas vía el package.json raíz del workspace, se recomienda configurar el Plugin ESLint de Verificación de Dependencias de Nx para asegurar que el package.json publicado incluye todas las dependencias usadas.

Compilación

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

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 de compilación 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 de tu proyecto.

Por ejemplo:

• Directorysrc

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

Vitest proporciona una 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 mock de dependencias, consulta la documentación de Vitest

Ejecutando pruebas

Las pruebas se ejecutarán como parte del objetivo build de tu proyecto, pero también puedes ejecutarlas por separado mediante 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 o un conjunto de pruebas usando 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, que permite ejecutar, monitorizar o depurar pruebas directamente 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 aquí aplicarán a todos los proyectos TypeScript y asegurarán consistencia.

Igualmente, puedes configurar Prettier en el archivo .prettierrc raíz.

Ejecutando el linter

Para invocar el linter y verificar tu proyecto, ejecuta 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

Similarmente, si quieres 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