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
}
}
tsBuildInfoFilesitú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.skipLibCheckomite 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.tsde 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 filesy no reconstruyó nada. Después de editar un archivo enpackages/lib, reconstruyó ese proyecto y luegoapps/web, que depende de él, y nada más. Ejecutetsc --build --verboseuna 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. DefinatsBuildInfoFileen una ruta dentro de la carpeta de salida (por ejemplodist/.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
tsccompleto 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.
Relacionado
- Acelere Playwright en un monorepo con GitHub ActionsAcelere las pruebas e2e de Playwright en un monorepo Node con GitHub Actions: compile la app una vez y omita e2e si no cambió.
- Añada una insignia de velocidad de CI a su READMEMuestre la velocidad de su CI con una insignia en el README: el tiempo mediano de ejecución en GitHub Actions, actualizado automáticamente. Gratis.
- CI más rápido para monorepos de Bazel en GitHub ActionsCI rápido con Bazel en GitHub Actions: detección de objetivos, caché remota, subidas de solo lectura en PR, sharding y flujo completo.
- CI más rápido para monorepos de Nx en GitHub ActionsHaga rápido su CI de Nx en GitHub Actions: nx affected con nx-set-shas, caché remota de Nx, distribución de tareas y flujo completo.