Saltar al contenido

Acelere un monorepo de TypeScript en GitHub Actions

Última actualización

En un monorepo de TypeScript, la instalación y las pruebas suelen no ser la parte más lenta del CI. Lo son la comprobación de tipos y el linting, porque cada job arranca en una máquina nueva y vuelve a revisar todos los archivos. Para acelerarlos, conserve el estado incremental del compilador entre ejecuciones, use cachés de lint que funcionen tras un git checkout nuevo y ejecute las comprobaciones como jobs en paralelo en lugar de una cadena larga.

Esta guía cubre esas tres cosas con YAML funcional. No repite cómo ejecutar solo los paquetes modificados; eso está en el CI más rápido para workspaces de pnpm. Para el enfoque general, lea cómo acelerar GitHub Actions.

Mida qué comprobación es lenta

Mida cada comprobación por separado antes de cambiar nada. En un workflow, dé a cada una un nombre de paso y lea las duraciones de los pasos en el resumen de la ejecución:

- name: typecheck
  run: pnpm -r --workspace-concurrency=4 run typecheck
- name: lint
  run: pnpm -r --workspace-concurrency=4 run lint
- name: test
  run: pnpm -r --workspace-concurrency=4 run test

Si una de las tres ocupa más de la mitad del job, arregle esa primero. Las secciones siguientes siguen el orden habitual de beneficio: comprobación de tipos, luego lint y, por último, la organización de los jobs.

Comprobación de tipos: builds incrementales

tsc --noEmit comprueba los tipos y no escribe nada. Con incremental activado, TypeScript también escribe un archivo .tsbuildinfo que registra lo que sabe de cada archivo, de modo que una ejecución posterior solo vuelve a comprobar los archivos modificados y los que dependen de ellos. En tsconfig.json:

{
  "compilerOptions": {
    "noEmit": true,
    "incremental": true,
    "tsBuildInfoFile": "node_modules/.cache/tsc/web.tsbuildinfo",
    "skipLibCheck": true
  }
}
  • tsBuildInfoFile sitúa el estado en una ruta que usted elige, así sabe exactamente qué cachear. Use un archivo por paquete, porque dos proyectos no deben escribir en el mismo archivo.
  • skipLibCheck omite la comprobación de tipos de los archivos .d.ts. La documentación de TypeScript lo describe como un ahorro de tiempo a costa de cierta precisión en el sistema de tipos. Su propio código sigue comprobándose. La mayoría de los CI aceptan ese compromiso.

Después restaure y guarde esa carpeta con la acción de caché:

- uses: actions/cache@v6
  with:
    path: node_modules/.cache/tsc
    key: tsc-${{ runner.os }}-${{ hashFiles('pnpm-lock.yaml') }}-${{ github.sha }}
    restore-keys: |
      tsc-${{ runner.os }}-${{ hashFiles('pnpm-lock.yaml') }}-
      tsc-${{ runner.os }}-
- run: pnpm -r run typecheck

La clave termina en el SHA del commit, así que cada ejecución guarda una copia nueva, y restore-keys carga la copia anterior más reciente. GitHub solo permite que una ejecución restaure cachés guardadas por su propia rama, por la rama base del pull request o por la rama por defecto, así que los pull requests parten de lo que guardó main. Esa es la caché que quiere: un PR vuelve a comprobar solo lo que cambió.

Un checkout nuevo da a cada archivo una hora de modificación nueva, pero eso no anula esta caché. Lo comprobamos con TypeScript 5.9.3: tras copiar un proyecto (marcas de tiempo nuevas) y tocar sus archivos sin cambiar su contenido, tsc --extendedDiagnostics seguía informando de menos tipos comprobados que una ejecución en frío, porque TypeScript compara el contenido de los archivos, no las fechas. Si el estado guardado no coincide con sus archivos, TypeScript los vuelve a comprobar, así que una caché obsoleta es más lenta, nunca incorrecta. Si sospecha de una, elimínela y vuelva a ejecutar.

Referencias de proyecto

Un monorepo con paquetes que se importan entre sí puede usar referencias de proyecto. Cada paquete define composite: true, y la raíz enumera los paquetes que construye:

{
  "files": [],
  "references": [
    { "path": "packages/ui" },
    { "path": "packages/api-client" },
    { "path": "apps/web" }
  ]
}
tsc --build

tsc --build (o -b) construye cada proyecto en orden de dependencias y omite los proyectos que ya están actualizados. Hay dos cosas que conviene saber antes de depender de ello en CI:

  • El modo build escribe la salida .d.ts de cada paquete referenciado, de modo que el siguiente paquete comprueba contra un archivo de declaraciones pequeño en lugar del código fuente completo. Ahí es donde baja el tiempo en grafos grandes.
  • El modo build puede omitir proyectos tras un checkout nuevo. Su primera comprobación son las marcas de tiempo, y un checkout hace que sus fuentes sean más nuevas que las salidas restauradas. Lo probamos exactamente así con TypeScript 5.9.3 y tsc --build --verbose: con contenido sin cambios informó up to date but needs to update timestamps of output files that are older than input files y no reconstruyó nada. Después de editar un archivo en packages/lib, reconstruyó ese proyecto y luego apps/web, que depende de él, y nada más. Ejecute tsc --build --verbose una vez en su runner tras restaurar la caché; el log indica para cada proyecto si se omitió o se reconstruyó, y por qué.
  • Para usarlo en CI, cachee la carpeta de salida de cada proyecto junto con su archivo .tsbuildinfo. Defina tsBuildInfoFile en una ruta dentro de la carpeta de salida (por ejemplo dist/.tsbuildinfo) para que una sola ruta cubra ambas cosas:
- uses: actions/cache@v6
  with:
    path: |
      packages/*/dist
      apps/*/dist
    key: tsb-${{ runner.os }}-${{ hashFiles('pnpm-lock.yaml') }}-${{ github.sha }}
    restore-keys: |
      tsb-${{ runner.os }}-${{ hashFiles('pnpm-lock.yaml') }}-

No active las referencias de proyecto solo porque estén de moda. Un repositorio con dos o tres paquetes gana poco. Un repositorio con muchos paquetes y un grafo de importaciones profundo gana mucho.

Lint: cachés que sobreviven a un checkout

ESLint puede guardar resultados por archivo y omitir los archivos sin cambios. Su estrategia por defecto, metadata, decide que un archivo no ha cambiado a partir de metadatos como la fecha de modificación. Un checkout nuevo da a cada archivo una hora nueva, así que la caché por defecto puede fallar en cada ejecución. ESLint y Prettier tienen una estrategia content que compara el contenido de los archivos:

eslint . --cache --cache-location node_modules/.cache/eslint/web.cache --cache-strategy content

Prettier acepta las mismas opciones:

prettier --check . --cache --cache-location node_modules/.cache/prettier/.prettier-cache --cache-strategy content

Cachee esas carpetas igual que el estado de TypeScript:

- uses: actions/cache@v6
  with:
    path: |
      node_modules/.cache/eslint
      node_modules/.cache/prettier
    key: lint-${{ runner.os }}-${{ hashFiles('pnpm-lock.yaml', '**/eslint.config.*', '**/.prettierrc*') }}-${{ github.sha }}
    restore-keys: |
      lint-${{ runner.os }}-${{ hashFiles('pnpm-lock.yaml', '**/eslint.config.*', '**/.prettierrc*') }}-

La clave incluye el lockfile y los archivos de configuración, porque una nueva versión de una regla o de un plugin debe invalidar los resultados anteriores.

Las reglas de lint con tipos cuestan más

Las reglas que necesitan información de tipos (reglas de @typescript-eslint como no-floating-promises) hacen que ESLint construya un programa de TypeScript, lo que es mucho más lento que las reglas basadas solo en sintaxis. La documentación de typescript-eslint indica que el lint con tipos es más lento que el lint sin tipos, y en las versiones actuales la forma de configurarlo es su opción projectService, en lugar de enumerar rutas project a mano. Opciones:

  • Active las reglas con tipos solo en las carpetas que las necesitan.
  • Ejecute la pasada con tipos como un job propio, para que los resultados rápidos de lint lleguen antes.
  • No ejecute a la vez un tsc completo y ESLint con tipos sobre cada archivo si para una regla concreta solo necesita uno de los dos.

Ejecute las comprobaciones como jobs en paralelo

Un único job que ejecuta typecheck, luego lint y luego test tarda la suma de los tres. Con tres jobs se tarda lo que dura el más largo, más una instalación por cada uno:

name: CI
on:
  push:
    branches: [main]
  pull_request:

concurrency:
  group: ci-${{ github.ref }}
  cancel-in-progress: true

jobs:
  typecheck:
    runs-on: [self-hosted, Linux, compiler-ci]   # or ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: pnpm/action-setup@v6
      - uses: actions/setup-node@v7
        with:
          node-version: 22
          cache: pnpm
      - run: pnpm install --frozen-lockfile
      - uses: actions/cache@v6
        with:
          path: node_modules/.cache/tsc
          key: tsc-${{ runner.os }}-${{ hashFiles('pnpm-lock.yaml') }}-${{ github.sha }}
          restore-keys: tsc-${{ runner.os }}-${{ hashFiles('pnpm-lock.yaml') }}-
      - run: pnpm -r run typecheck

  lint:
    runs-on: [self-hosted, Linux, compiler-ci]
    steps:
      - uses: actions/checkout@v6
      - uses: pnpm/action-setup@v6
      - uses: actions/setup-node@v7
        with:
          node-version: 22
          cache: pnpm
      - run: pnpm install --frozen-lockfile
      - uses: actions/cache@v6
        with:
          path: node_modules/.cache/eslint
          key: lint-${{ runner.os }}-${{ hashFiles('pnpm-lock.yaml') }}-${{ github.sha }}
          restore-keys: lint-${{ runner.os }}-${{ hashFiles('pnpm-lock.yaml') }}-
      - run: pnpm -r run lint

  test:
    runs-on: [self-hosted, Linux, compiler-ci]
    steps:
      - uses: actions/checkout@v6
      - uses: pnpm/action-setup@v6
      - uses: actions/setup-node@v7
        with:
          node-version: 22
          cache: pnpm
      - run: pnpm install --frozen-lockfile
      - run: pnpm -r run test

cancel-in-progress detiene las ejecuciones anteriores de la misma rama cuando vuelve a subir cambios, lo que también ahorra minutos; consulte cómo reducir su factura de GitHub Actions. Cada job instala dependencias, así que mantenga en caché el store de pnpm; el almacenamiento en caché de pnpm en GitHub Actions incluye los detalles. La división compensa cuando la instalación es corta en comparación con las comprobaciones. Si la instalación es lo más lento, un único job será más rápido.

Marque las comprobaciones como obligatorias en la protección de ramas usando el nombre del job, para que un job lento no se omita por error.

Lo que aportan más núcleos de CPU

tsc es mayormente de un solo hilo para un proyecto, pero un monorepo tiene muchos proyectos, y pnpm -r los ejecuta en paralelo, al igual que ESLint en todos los paquetes y el ejecutor de tests. Con más núcleos, ajuste --workspace-concurrency en consecuencia, por ejemplo 8 en una máquina de 8 núcleos. La memoria también importa: una ejecución grande de ESLint con reglas basadas en tipos puede necesitar varios gigabytes, y un runner alojado de 2 vCPU tiene 7 GB en total.

Para ver lo que gana su repositorio, cambie una línea a runs-on: [self-hosted, Linux, compiler-ci] y compare los tiempos de ejecución, o use el modo de comparación, que ejecuta una copia de sus jobs junto a los actuales. Consulte precios, comparar y nuestros benchmarks. Para el resto del pipeline, empiece por el centro de CI lento.

Preguntas frecuentes

¿Debo almacenar en caché el archivo .tsbuildinfo?

Sí, si la comprobación de tipos supone una parte importante del job. Establezca tsBuildInfoFile en una ruta conocida y guarde en caché esa carpeta. Si la caché está desactualizada, TypeScript comprueba más archivos, así que es seguro.

¿Funciona tsc --build con caché en CI?

Sí. En TypeScript 5.9.3 se usó una caché restaurada aunque un checkout nuevo hiciera que los fuentes fueran más recientes que las salidas, siempre que su contenido no hubiera cambiado. Ejecute tsc --build --verbose una vez tras restaurar la caché para ver qué proyectos se omiten en su versión.

¿Es seguro skipLibCheck?

Omite la comprobación de los archivos de declaración, por lo que no se informan errores en los tipos de sus dependencias. Los errores en su propio código sí se informan. La mayoría de los equipos lo activa.

¿Por qué la caché de ESLint nunca se aprovecha en CI?

La estrategia predeterminada (metadata) detecta cambios a partir de metadatos del archivo, como la fecha de modificación, y un checkout nuevo cambia todos ellos. Use --cache-strategy content y guarde en caché la carpeta que contiene el archivo de caché.

¿Deben typecheck, lint y test ser jobs separados?

Cuando cada uno tarda unos minutos, sí. Cuando la instalación es la mayor parte de cada job, no: se paga tres veces.

Ejecute esta build de monorepo en compiler.dev Sin tarjeta · 200 minutos gratuitos

Pruébelo gratis