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 crear 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	-	Library 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.

Resultado 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 espacio de trabajo)
• 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é a continuación.

También notarás cambios en los siguientes archivos del directorio raíz:

• nx.json La configuración de Nx se actualiza para configurar el plugin @nx/js/typescript para tu proyecto
• tsconfig.base.json Se establece 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

Al ser tu proyecto un Módulo ES, usa la sintaxis ESM correcta en las importaciones, incluyendo explícitamente la extensión de 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. Más detalles aquí.

Exportar para otros proyectos TypeScript

El punto de entrada es src/index.ts. Añade aquí las exportaciones que quieras compartir:

src/index.ts

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

Importar tu biblioteca en otros proyectos

Los alias TypeScript configurados en tsconfig.base.json permiten referenciar tu proyecto desde otros:

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

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

Nota

Los alias comienzan con : para evitar conflictos con paquetes remotos en NPM.

Al añadir una importación a un nuevo proyecto, podrías ver un error como 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 falta una referencia de proyecto.

Los proyectos TypeScript vienen configurados con el generador de sincronización de Nx. Ejecuta este comando para añadir la configuración necesaria:

pnpm

pnpm nx sync

yarn

yarn nx sync

npm

npx nx sync

bun

bunx nx sync

Tras esto, el error debería desaparecer.

Consejo

Al compilar tu proyecto, 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 actualizar las referencias.

Dependencias

Tu proyecto TypeScript no tiene package.json. Para añadir dependencias:

1. Añádelas al package.json raíz de tu espacio de trabajo usando 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

Código de ejecución

Para usar tu proyecto como código de ejecución (ej: en AWS Lambda), se recomienda usar esbuild para empaquetarlo y aplicar tree-shaking.

Añade un objetivo como este en 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

El punto de entrada src/index.ts incluirá en el bundle todo su código y dependencias.

Publicar en NPM

Si publicas tu proyecto en NPM, debes crear un package.json. Usa el plugin ESLint de NX para verificar dependencias.

Compilación

El objetivo build compila, verifica y prueba tu proyecto. Ejecútalo 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

La salida se encuentra en dist/packages/<my-library>/tsc.

Pruebas

Vitest está configurado para testing.

Escribir pruebas

Crea archivos .spec.ts o .test.ts junto a tu código:

• Directorysrc

  • hello.ts Código fuente
  • hello.spec.ts Pruebas para hello.ts

Ejemplo de prueba:

hello.spec.ts

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

describe('sayHello', () => {

  it('debería saludar al usuario', () => {
    expect(sayHello('Darth Vader')).toBe('¡Hola, Darth Vader!');
  });

});

Consulta la documentación de Vitest para más detalles.

Ejecutar pruebas

Ejecuta todas las pruebas con:

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

Para pruebas específicas:

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

Usuarios de VSCode: instala la extensión Vitest Runner para ejecutar pruebas desde el IDE.

Linting

Los proyectos usan ESLint y Prettier. Configúralos en los archivos raíz eslint.config.mjs y .prettierrc.

Ejecutar el linter

Verifica tu proyecto con:

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

Corregir problemas

Corrige automáticamente con:

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 todo el espacio de trabajo:

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