```
### 5. Container queries
Antes requería un plugin. Ahora viene integrado en v4:
```html
```
## Dark mode sin el flash
Tailwind v4 mejora el soporte para dark mode basado en clases.
### La configuración que recomiendo
```css
@import "tailwindcss";
@variant dark (&:where(.dark, .dark *));
```
Esto permite:
```html
```
### Evitar FOUC (Flash of Unstyled Content)
```html
```
## La herramienta de upgrade hace la mitad del trabajo
```bash
npx @tailwindcss/upgrade
```
La ejecutas y convierte `tailwind.config.js` a `@theme` en tu CSS, actualiza los imports en los archivos y detecta plugins incompatibles. Útil.
Lo que **no** hace: migrar custom utilities (eso te toca a ti) ni arreglar `@apply` dentro de keyframes (esos los reescribes a mano). Reserva tiempo para ambas cosas.
## Trucos de producción que sobrevivieron a la migración
### 1. Purge agresivo (ya no hace falta)
En v3 tenías que configurar `purge`. En v4 el tree-shaking es automático y más inteligente. Una cosa menos.
### 2. Usar CSS nesting
```css
/* Aprovecha el nesting nativo de CSS */
.card {
@apply rounded-lg shadow-md;
&:hover {
@apply shadow-xl scale-105;
}
& .card-title {
@apply text-xl font-bold;
}
}
```
### 3. Optimizar fuentes con variables CSS
```css
@theme {
--font-sans: 'Inter var', system-ui, sans-serif;
--font-mono: 'JetBrains Mono', monospace;
}
```
Luego usa `font-variation-settings` para weights dinámicos:
```css
.dynamic-weight {
font-variation-settings: 'wght' var(--font-weight);
}
```
## Tres migraciones, tres facturas
### Portfolio personal (20 páginas)
- **Tiempo de migración:** 2 horas
- **Build time:** 6.2s → 0.78s
- **Problemas encontrados:** 3 custom plugins (reescritos a CSS)
### Dashboard SaaS (150 componentes)
- **Tiempo de migración:** 1 día
- **Build time:** 14.5s → 1.2s
- **Problemas encontrados:** `@apply` en keyframes (8 casos), plugin de animaciones custom
### E-commerce (300+ componentes)
- **Tiempo de migración:** 2 días
- **Build time:** 28s → 2.1s
- **Problemas encontrados:** conflicto con @astrojs/tailwind, 15 utilities custom migradas
## ¿Vale la pena migrar ahora?
**Sí, si:**
- Tu build time es >5 segundos
- Usas Vite/Astro (mejor integración)
- Estás empezando un proyecto nuevo
- Quieres aprovechar container queries nativas
**Espera, si:**
- Tienes muchos plugins custom incompatibles
- Tu equipo no puede dedicar 1-2 días a la migración
- Dependes de `@apply` en keyframes intensivamente
- Usas frameworks que aún no soportan v4 oficialmente
## Tres meses en producción, y la factura salió a favor
El marcador después de 3 meses con v4:
- **Deploy times:** reducidos en un 65%
- **Developer experience:** HMR instantáneo (sin lag perceptible)
- **Bundle size:** 10-15% más pequeño
- **Bugs:** solo 2 edge cases con dark mode en Safari
Dos edge cases en Safari es una factura que pago encantado a cambio de un build de 890ms. La migración duele al principio. Luego tus rebuilds tardan 45ms y dejas de pensar en tu herramienta de build, que es el mejor cumplido que una herramienta de build puede ganarse.
Si tu build tarda más de 5 segundos, ya sabes qué hacer con tu próxima tarde libre.
**Lectura relacionada:** el setup de este post asume Astro. Si todavía estás decidiendo el framework, empieza por [cómo Astro dejó este sitio en 18KB de JavaScript](/blog/introduccion-astro-5/).
---
**P.D.** ¿Migrando un proyecto v3 y te has topado con algo que este post no cubre? Cuéntamelo en [Twitter/X](https://x.com/garbarok).
---
# TypeScript Best Practices: Cut 90% of Production Bugs
URL: https://www.oscargallegoruiz.com/en/blog/typescript-best-practices/
Lang: en
> A strict tsconfig.json and advanced types took our production bugs from 47 to 3 in six months. The setup, the types that did the work, and where it hurt. →
Two years ago I inherited a project with 80,000 lines of pure JavaScript. The scoreboard: **47 production bugs in 3 months**.
After migrating to TypeScript with a strict configuration, that number dropped to 3 bugs in 6 months. Forty-seven to three.
TypeScript isn't just "JavaScript with types." It's an error prevention system that starts paying on day one, but only if you configure it to actually say no.
## The five practices that did the work
The whole post boils down to a strict configuration plus advanced use of the type system, so errors die at compile time instead of in production.
- **Enable strict mode:** turn on all the `strict` flags in your `tsconfig.json` for maximum safety.
- **Use `noUncheckedIndexedAccess`:** prevent `undefined` errors when accessing arrays and objects.
- **Differentiate `type` and `interface`:** `type` for unions and complex types, `interface` for objects and public APIs that can be extended.
- **Master utility types:** `Awaited`, `Parameters`, `ReturnType`, `Extract`, and `Exclude` manipulate types so you don't repeat them.
- **Apply type narrowing:** type guards, discriminated unions, and the `asserts` keyword refine types and guide the compiler.
## A strict `tsconfig.json` is your first line of defense
Most developers don't enable all the strict flags. That's the costly mistake.
### The core flags
The foundational settings for a robust setup.
```json
{
"compilerOptions": {
"strict": true,
"strictNullChecks": true,
"strictFunctionTypes": true,
"strictBindCallApply": true,
"strictPropertyInitialization": true,
"noImplicitThis": true,
"alwaysStrict": true
}
}
```
### The flags that catch the weird stuff
Go beyond the basics and more bugs die at compile time.
```json
{
"compilerOptions": {
// ... core flags
"noUncheckedIndexedAccess": true, // Critical
"noImplicitOverride": true, // Avoids inheritance bugs
"noImplicitReturns": true, // Forces explicit returns
"noFallthroughCasesInSwitch": true, // Catch switch bugs
"noUnusedLocals": true, // Cleans dead code
"noUnusedParameters": true, // Detects unused params
"exactOptionalPropertyTypes": true, // Differentiates undefined from absent
"noPropertyAccessFromIndexSignature": true // Forces bracket notation
}
}
```
### Config for modern tooling
This keeps you compatible with Vite, Astro, and Next.js.
```json
{
"compilerOptions": {
// ... other flags
"module": "ESNext",
"moduleResolution": "bundler",
"resolveJsonModule": true,
"allowImportingTsExtensions": true,
"noEmit": true,
"esModuleInterop": true,
"allowSyntheticDefaultImports": true,
"isolatedModules": true,
"target": "ES2022",
"lib": ["ES2023", "DOM", "DOM.Iterable"],
"skipLibCheck": true,
"forceConsistentCasingInFileNames": true
}
}
```
### `noUncheckedIndexedAccess`: one flag, 23 bugs
Without this flag, accessing an array index is always assumed to be safe. That assumption is a common source of runtime errors.
> With `noUncheckedIndexedAccess: false` (the default), `users[10]` has the type `string`, which is a lie.
> With `noUncheckedIndexedAccess: true`, `users[10]` has the type `string | undefined`, which is the truth.
This single flag forced me to add proper checks and uncovered **23 potential bugs** in an existing project.
Here's the honest part. "Forced" is the right word: the flag is annoying exactly as often as your code was wrong, and you pay that bill up front, at every indexed access, before you've shipped anything. Potential bugs, too, not 23 production crashes. Strictness is friction by design. You're trading an afternoon of compiler complaints for the 2 a.m. `undefined is not a function`. I'll take the compiler.
## `type` vs `interface`: the rule that ends the debate
The general rule: `interface` for the shape of objects and for public APIs (because it can be extended), `type` for everything else (unions, primitives, complex types).
The side-by-side:
| Feature | `interface` | `type` |
| --------------------- | ----------------------------------------------- | ---------------------------------------------------- |
| **Ideal for** | Object structures (OOP), public APIs | Unions, primitives, complex types, functions |
| **Extending** | Yes, with `extends` and declaration merging | Not directly; achieved with intersections (`&`) |
| **Declaration Merging** | Yes (allows adding new fields) | No (throws a duplicate identifier error) |
| **Unions & Primitives** | No, cannot be used for `string \| number` or `string` | Yes (`type ID = string \| number;`) |
| **Tuples** | No | Yes (`type Point = [number, number];`) |
| **Mapped Types** | No | Yes (`type Readonly
= ...`) |
### The short version
- **Use `interface` when:**
- Defining the "shape" of an object or class.
- You want users of your API to be able to extend the definition (e.g., plugins).
- **Use `type` when:**
- You need unions, tuples, or function types.
- You need complex types built with mapped types or conditionals.
## Utility types that earn their keep
### `Awaited`
Unwraps the type from a `Promise`. Essential for inferring the return type of async functions.
```typescript
async function fetchUser() {
return { id: '1', name: 'Alice' };
}
type User = Awaited>;
// User is { id: string; name: string }
```
### `Parameters` and `ReturnType`
Extract parameter and return types from a function. Perfect for wrappers and decorators.
```typescript
function createUser(name: string, age: number) { /* ... */ }
type CreateUserParams = Parameters; // [string, number]
```
### `Extract` and `Exclude`
Filter types from a union based on a condition.
```typescript
type Event =
| { type: 'click'; x: number; y: number }
| { type: 'keypress'; key: string };
// Extracts only the click event
type MouseEvent = Extract;
```
## Narrowing: tell the compiler what you already know
### User-defined type guards
A function that returns a boolean and signals a type to TypeScript.
```typescript
function isCat(animal: Animal): animal is Cat {
return animal.type === 'cat';
}
```
### Discriminated unions
A common property (like `status` or `type`) turns your states into a machine TypeScript can follow.
```typescript
type LoadingState =
| { status: 'loading' }
| { status: 'success'; data: string };
function handleState(state: LoadingState) {
if (state.status === 'success') {
console.log(state.data); // TS knows `data` exists
}
}
```
### The `asserts` keyword
A function that throws when a type condition isn't met, asserting the type for the rest of the block.
```typescript
function assertIsString(value: unknown): asserts value is string {
if (typeof value !== 'string') {
throw new Error('Not a string');
}
}
```
## Five years in: the numbers
After 5 years of TypeScript in production environments:
- **Runtime bugs:** reduced by 85%.
- **Refactoring time:** 60% faster due to type safety.
- **Developer onboarding:** 40% faster because the code is self-documenting.
Every hour spent configuring types correctly saves ten hours of future debugging.
So open your `tsconfig.json` and count the flags from this post that are missing. Each one is a category of bug you've agreed to find in production instead.
**Related reading:** strict types catch what your laptop forgives, and CI is the other half of that story. See [why tests pass locally and fail on Vercel](/en/blog/tests-pass-locally-fail-vercel/).
---
**P.S.** Got a strict flag horror story, or a flag you think is overrated? Tell me on [Twitter/X](https://x.com/garbarok).
---
# Buenas Prácticas en TypeScript: Reduce 90% los Bugs
URL: https://www.oscargallegoruiz.com/blog/typescript-mejores-practicas/
Lang: es
> Un tsconfig.json estricto y tipos avanzados bajaron nuestros bugs en producción de 47 a 3. El setup, los tipos que hicieron el trabajo y dónde dolió. →
Hace 2 años heredé un proyecto con 80,000 líneas de JavaScript puro. El marcador: **47 bugs en producción en 3 meses**.
Después de migrar a TypeScript con una configuración estricta, ese número bajó a 3 bugs en 6 meses. De cuarenta y siete a tres.
TypeScript no es solo "JavaScript con tipos". Es un sistema de prevención de errores que empieza a pagar desde el primer día, pero solo si lo configuras para que de verdad diga que no.
## Las cinco prácticas que hicieron el trabajo
Todo el post se reduce a una configuración estricta más un uso avanzado del sistema de tipos, para que los errores mueran en tiempo de compilación y no en producción.
- **Activa el modo estricto:** habilita todos los flags de `strict` en tu `tsconfig.json` para la máxima seguridad.
- **Usa `noUncheckedIndexedAccess`:** evita errores de `undefined` al acceder a arrays y objetos.
- **Diferencia `type` e `interface`:** `type` para uniones y tipos complejos, `interface` para objetos y APIs públicas que pueden extenderse.
- **Domina los utility types:** `Awaited`, `Parameters`, `ReturnType`, `Extract` y `Exclude` manipulan tipos para que no los repitas.
- **Aplica type narrowing:** type guards, uniones discriminadas y la palabra clave `asserts` refinan los tipos y guían al compilador.
## Un `tsconfig.json` estricto es tu primera línea de defensa
La mayoría de los desarrolladores no activan todos los flags estrictos. Ese es el error caro.
### Los flags fundamentales
La base de un setup robusto.
```json
{
"compilerOptions": {
"strict": true,
"strictNullChecks": true,
"strictFunctionTypes": true,
"strictBindCallApply": true,
"strictPropertyInitialization": true,
"noImplicitThis": true,
"alwaysStrict": true
}
}
```
### Los flags que cazan lo raro
Ve más allá de lo básico y más bugs mueren en tiempo de compilación.
```json
{
"compilerOptions": {
// ... flags fundamentales
"noUncheckedIndexedAccess": true, // Crítico
"noImplicitOverride": true, // Evita bugs en herencia
"noImplicitReturns": true, // Fuerza returns explícitos
"noFallthroughCasesInSwitch": true, // Atrapa bugs en switch
"noUnusedLocals": true, // Limpia código muerto
"noUnusedParameters": true, // Detecta parámetros no usados
"exactOptionalPropertyTypes": true, // Diferencia undefined de ausente
"noPropertyAccessFromIndexSignature": true // Fuerza notación de corchetes
}
}
```
### Configuración para tooling moderno
Esto te mantiene compatible con Vite, Astro y Next.js.
```json
{
"compilerOptions": {
// ... otros flags
"module": "ESNext",
"moduleResolution": "bundler",
"resolveJsonModule": true,
"allowImportingTsExtensions": true,
"noEmit": true,
"esModuleInterop": true,
"allowSyntheticDefaultImports": true,
"isolatedModules": true,
"target": "ES2022",
"lib": ["ES2023", "DOM", "DOM.Iterable"],
"skipLibCheck": true,
"forceConsistentCasingInFileNames": true
}
}
```
### `noUncheckedIndexedAccess`: un flag, 23 bugs
Sin este flag, se asume que acceder a un índice de un array siempre es seguro. Esa suposición es una fuente común de errores en tiempo de ejecución.
> Con `noUncheckedIndexedAccess: false` (el valor por defecto), `users[10]` tiene el tipo `string`, lo cual es una mentira.
> Con `noUncheckedIndexedAccess: true`, `users[10]` tiene el tipo `string | undefined`, lo cual es la verdad.
Este único flag me obligó a añadir verificaciones adecuadas y descubrió **23 bugs potenciales** en un proyecto existente.
Aquí va la parte honesta. "Obligó" es la palabra exacta: el flag molesta exactamente tantas veces como tu código estaba mal, y esa factura la pagas por adelantado, en cada acceso indexado, antes de haber publicado nada. Y son bugs potenciales, no 23 crashes en producción. La estrictez es fricción por diseño. Cambias una tarde de quejas del compilador por el `undefined is not a function` de las 2 de la mañana. Yo me quedo con el compilador.
## `type` vs `interface`: la regla que cierra el debate
La regla general: `interface` para la forma de objetos y para APIs públicas (porque puede extenderse), `type` para todo lo demás (uniones, primitivos, tipos complejos).
La comparación directa:
| Característica | `interface` | `type` |
| --------------------- | ------------------------------------------------- | ------------------------------------------------------ |
| **Ideal para** | Estructuras de objetos (OOP), APIs públicas | Uniones, primitivos, tipos complejos, funciones |
| **Extensión** | Sí, con `extends` y *declaration merging* | No directamente; se logra con intersecciones (`&`) |
| **Declaration Merging** | Sí (permite añadir nuevos campos) | No (genera un error de duplicado) |
| **Uniones y Primitivos**| No, no se puede usar para `string \| number` o `string` | Sí (`type ID = string \| number;`) |
| **Tuplas** | No | Sí (`type Point = [number, number];`) |
| **Mapped Types** | No | Sí (`type Readonly = ...`) |
### La versión corta
- **Usa `interface` cuando:**
- Defines la "forma" de un objeto o una clase.
- Quieres que los usuarios de tu API puedan extender la definición (ej. plugins).
- **Usa `type` cuando:**
- Necesitas uniones, tuplas o tipos de función.
- Necesitas tipos complejos construidos con mapped types o condicionales.
## Utility types que se ganan el sueldo
### `Awaited`
Desenvuelve el tipo de una `Promise`. Esencial para inferir el tipo de retorno de funciones asíncronas.
```typescript
async function fetchUser() {
return { id: '1', name: 'Alice' };
}
type User = Awaited>;
// User es { id: string; name: string }
```
### `Parameters` y `ReturnType`
Extraen los tipos de los parámetros y del retorno de una función. Perfectos para wrappers y decoradores.
```typescript
function createUser(name: string, age: number) { /* ... */ }
type CreateUserParams = Parameters; // [string, number]
```
### `Extract` y `Exclude`
Filtran tipos de una unión basándose en una condición.
```typescript
type Event =
| { type: 'click'; x: number; y: number }
| { type: 'keypress'; key: string };
// Extrae solo el evento de click
type MouseEvent = Extract;
```
## Narrowing: dile al compilador lo que tú ya sabes
### Type guards definidos por el usuario
Una función que devuelve un booleano y le señala un tipo a TypeScript.
```typescript
function isCat(animal: Animal): animal is Cat {
return animal.type === 'cat';
}
```
### Uniones discriminadas
Una propiedad común (como `status` o `type`) convierte tus estados en una máquina que TypeScript puede seguir.
```typescript
type LoadingState =
| { status: 'loading' }
| { status: 'success'; data: string };
function handleState(state: LoadingState) {
if (state.status === 'success') {
console.log(state.data); // TS sabe que `data` existe
}
}
```
### La palabra clave `asserts`
Una función que lanza un error si una condición de tipo no se cumple, afirmando el tipo para el resto del bloque.
```typescript
function assertIsString(value: unknown): asserts value is string {
if (typeof value !== 'string') {
throw new Error('No es un string');
}
}
```
## Cinco años después: los números
Tras 5 años usando TypeScript en entornos de producción:
- **Bugs en runtime:** reducidos en un 85%.
- **Tiempo de refactorización:** 60% más rápido gracias a la seguridad de tipos.
- **Onboarding de desarrolladores:** 40% más rápido porque el código se autodocumenta.
Cada hora invertida en configurar tipos correctamente ahorra diez horas de depuración futura.
Así que abre tu `tsconfig.json` y cuenta cuántos flags de este post te faltan. Cada uno es una categoría de bug que has aceptado encontrar en producción.
**Lectura relacionada:** los tipos estrictos cazan lo que tu portátil perdona, y la CI es la otra mitad de esa historia. Mira [por qué los tests pasan en local y fallan en Vercel](/blog/tests-localmente-fallan-vercel/).
---
**P.D.** ¿Tienes una historia de terror con un flag estricto, o un flag que te parece sobrevalorado? Cuéntamelo en [Twitter/X](https://x.com/garbarok).
---
# Vercel CI Hell: Fix Next.js Tests Failing in Production
URL: https://www.oscargallegoruiz.com/en/blog/tests-pass-locally-fail-vercel/
Lang: en
> Tests pass locally but fail on Vercel? The real fix is one line: NODE_ENV in vitest.config.ts, plus CI-aware timeouts. My 4 wasted hours, condensed. →
## Why do my tests pass locally but fail on Vercel?
When tests work on your machine but die in Vercel's CI, it's usually two environment differences: an incorrect `NODE_ENV` configuration, and timeouts tuned for hardware 5-10x faster than the CI container.
The fast checklist:
1. **Force `NODE_ENV` to `'test'`.** Your `vitest.config.ts` needs `env: { NODE_ENV: 'test' }`. Vercel might default to production mode, which strips out React's testing utilities.
2. **Raise timeouts for CI.** Vercel's CI is 5-10x slower than a local machine. Make timeouts environment-aware: `const TIMEOUT = process.env.CI ? 10000 : 5000;`.
3. **Read the Vercel logs.** Look for the specific tests that fail or crawl. The `actImplementation is not a function` error is often a symptom of the `NODE_ENV` issue.
4. **Mock heavy operations.** No file I/O, no giant test data. Lightweight mocks instead.
5. **Don't blame the libraries yet.** Before assuming version compatibility problems, check your environment configuration. It's the most common cause.
The rest of this post is how I learned each of those the slow way.
## Same code, same dependencies, different results
```bash
# Local
$ pnpm test
✓ All tests pass (181 passed)
# Vercel
❌ Build failed
Error: actImplementation is not a function
```
**Stack**: Next.js 16, React 19, Vitest, Vercel
**Time wasted**: 4 hours chasing the wrong problem
**Root cause**: misunderstanding Vercel's CI environment
## What I thought it was (the embarrassing part)
"React 19 compatibility issue with Testing Library!"
So I built, in order:
- a 125-line patch script for React internals
- a custom Vite plugin for module resolution
- mock files and import redirects
All of it failed on Vercel. All of it unnecessary. Four hours of confident engineering, aimed at a problem that didn't exist.
## The real problem
### Your machine is not Vercel's CI
**Local development:**
- Fast SSD, direct I/O
- Dedicated CPU/memory
- React loads in development mode
- Consistent environment
**Vercel CI:**
- Networked storage (slower I/O)
- Shared container resources
- May default to production mode
- Cold starts every build
The result: operations take 5-10x longer on Vercel.
## The two actual issues
### Issue 1: the environment mode
Vercel wasn't loading React in test mode by default.
The fix:
```typescript
// vitest.config.ts
import { defineConfig } from 'vitest/config'
import react from '@vitejs/plugin-react'
export default defineConfig({
plugins: [react()],
test: {
environment: 'jsdom',
// ← Forces React test mode
env: {
NODE_ENV: 'test',
},
},
})
```
Why this matters: React's development build includes test utilities, and the production build strips them out. Without `NODE_ENV: 'test'`, React loads incorrectly on Vercel.
### Issue 2: resource constraints
CI containers are slower. Operations that feel instant locally time out on Vercel.
The fix:
```typescript
// CI-aware timeout configuration
const TIMEOUT = process.env.CI ? 10000 : 5000
it('resource-intensive test', async () => {
// test code
}, TIMEOUT)
```
A real measurement from this debugging session:
```typescript
// Creating a 100MB test file
const largeFile = createMockImageFile(
'large.jpg',
100 * 1024 * 1024,
'image/jpeg'
)
// Local: ~500ms
// Vercel CI: ~6-7 seconds (!)
```
## The minimal configuration that works
```typescript
// vitest.config.ts
import { defineConfig } from 'vitest/config'
import react from '@vitejs/plugin-react'
import tsconfigPaths from 'vite-tsconfig-paths'
export default defineConfig({
plugins: [tsconfigPaths(), react()],
test: {
environment: 'jsdom',
setupFiles: ['./src/test/setup.ts'],
globals: true,
css: true,
// Critical for Vercel CI
env: {
NODE_ENV: 'test',
},
// Global timeout with CI awareness
testTimeout: process.env.CI ? 10000 : 5000,
},
})
```
### Environment-aware test timeouts
```typescript
// test-config.ts
export const TEST_TIMEOUTS = {
FAST: process.env.CI ? 5000 : 2000,
MEDIUM: process.env.CI ? 10000 : 5000,
SLOW: process.env.CI ? 30000 : 15000,
}
// In your tests
import { TEST_TIMEOUTS } from './test-config'
describe('Feature', () => {
it('fast operation', async () => {
// Quick unit test
}, TEST_TIMEOUTS.FAST)
it('file I/O operation', async () => {
// File processing, small data
}, TEST_TIMEOUTS.MEDIUM)
it('complex operation', async () => {
// Large files, network, heavy processing
}, TEST_TIMEOUTS.SLOW)
})
```
## The diagnostic checklist for next time
When tests fail on Vercel but pass locally:
1. Check that `NODE_ENV: 'test'` is set in `vitest.config`
2. Read the Vercel build logs for slow tests
3. Add explicit timeouts to resource-intensive tests
4. Use environment-aware configuration
5. Mock expensive operations (file I/O, large data)
6. Do not start by assuming library incompatibility
### Common patterns
```typescript
// ❌ Assumes local environment
it('test', async () => {
await heavyOperation()
})
// ✅ Accounts for CI differences
it('test', async () => {
await heavyOperation()
}, process.env.CI ? 15000 : 5000)
```
```typescript
// ❌ Creating real 100MB files
const largeFile = createRealFile(100 * 1024 * 1024)
// ✅ Use lightweight mocks
const largeFile = createMockFile({ size: 100 * 1024 * 1024 })
```
## What four wasted hours taught me
### 1. Vercel CI is not your MacBook
Design tests with CI in mind from the start: containerized builds, shared resources, slower I/O, different defaults.
### 2. Configure explicitly
Don't rely on default behavior. Set `NODE_ENV` explicitly, set timeouts for slow operations, make configs environment-aware.
### 3. Error messages can mislead
`actImplementation is not a function` looked like a React compatibility problem. The actual cause: React loading in the wrong mode due to environment misconfiguration.
### 4. Design for CI from the start
Write tests knowing they'll run on slower infrastructure. Account for cold container starts, networked storage, resource throttling, and shared CPU and memory.
## What makes Vercel's build environment different
**Containerized builds.** Each build runs in an isolated container. Containers share infrastructure resources, and I/O is networked, not local.
**Cold starts.** Containers spin up fresh for each build. No warm filesystem cache, dependencies downloaded every time.
**Resource limits.** CPU/memory throttling, shared infrastructure, different performance characteristics.
**Environment variables.** Different defaults than your local `.env`. `NODE_ENV` might not be what you expect, so configure it explicitly.
## Configure for it. Don't fight it.
Vercel's CI is slower than your machine (5-10x), runs Node.js differently, and needs explicit configuration to behave.
The error message pointed at React. The problem was Vercel's environment. Knowing the difference is the whole fix, and it's a one-line config change once you stop patching React internals.
## Sources
- [Vitest Environment Configuration](https://vitest.dev/config/#environment)
- [Vercel Build Configuration](https://vercel.com/docs/build-step)
- [Next.js Testing Best Practices](https://nextjs.org/docs/testing)
**Related reading:** another afternoon lost to a tool silently ignoring my config: [the misplaced `content.config.ts` that ate my Astro schema fields](/en/blog/astro-content-config-location/).
---
**P.S.** Fought your own round with Vercel's CI? Tell me what the error message claimed and what the problem actually was, on [Twitter/X](https://x.com/garbarok).
---
# Infierno en Vercel CI: Arregla Tests de Next.js Fallando
URL: https://www.oscargallegoruiz.com/blog/tests-localmente-fallan-vercel/
Lang: es
> ¿Tus tests pasan en local pero fallan en Vercel? El arreglo es una línea: NODE_ENV en vitest.config.ts, más timeouts para CI. 4 horas perdidas, resumidas. →
## ¿Por qué mis tests pasan en local pero fallan en Vercel?
Cuando los tests funcionan en tu máquina pero mueren en el CI de Vercel, suelen ser dos diferencias de entorno: una configuración incorrecta de `NODE_ENV` y timeouts pensados para hardware 5-10 veces más rápido que el contenedor del CI.
La checklist rápida:
1. **Fuerza `NODE_ENV` a `'test'`.** Tu `vitest.config.ts` necesita `env: { NODE_ENV: 'test' }`. Vercel puede usar el modo de producción por defecto, lo que elimina utilidades de testing de React.
2. **Sube los timeouts para CI.** El CI de Vercel es 5-10 veces más lento que una máquina local. Haz los timeouts conscientes del entorno: `const TIMEOUT = process.env.CI ? 10000 : 5000;`.
3. **Lee los logs de Vercel.** Busca los tests concretos que fallan o se arrastran. El error `actImplementation is not a function` suele ser un síntoma del problema de `NODE_ENV`.
4. **Mockea las operaciones pesadas.** Nada de I/O de archivos ni datos gigantes en los tests. Mocks ligeros.
5. **No culpes a las librerías todavía.** Antes de pensar en problemas de compatibilidad entre versiones, revisa la configuración del entorno. Es la causa más común.
El resto del post es cómo aprendí cada uno de esos puntos por el camino lento.
## Mismo código, mismas dependencias, resultados diferentes
```bash
# Local
$ pnpm test
✓ Todos los tests pasan (181 pasados)
# Vercel
❌ Build fallido
Error: actImplementation is not a function
```
**Stack**: Next.js 16, React 19, Vitest, Vercel
**Tiempo perdido**: 4 horas persiguiendo el problema equivocado
**Causa raíz**: malentender el entorno CI de Vercel
## Lo que pensé que era (la parte vergonzosa)
"¡Problema de compatibilidad de React 19 con Testing Library!"
Así que construí, por este orden:
- un script de parcheo de 125 líneas para internals de React
- un plugin de Vite personalizado para resolución de módulos
- archivos mock y redirecciones de imports
Todo falló en Vercel. Todo era innecesario. Cuatro horas de ingeniería muy segura de sí misma, apuntando a un problema que no existía.
## El problema real
### Tu máquina no es el CI de Vercel
**Desarrollo local:**
- SSD rápido, I/O directo
- CPU/memoria dedicada
- React se carga en modo desarrollo
- Entorno consistente
**CI de Vercel:**
- Almacenamiento en red (I/O más lento)
- Recursos de contenedor compartidos
- Puede usar modo producción por defecto
- Arranques en frío en cada build
El resultado: las operaciones tardan 5-10x más en Vercel.
## Los dos problemas de verdad
### Problema 1: el modo de entorno
Vercel no estaba cargando React en modo test por defecto.
La solución:
```typescript
// vitest.config.ts
import { defineConfig } from 'vitest/config'
import react from '@vitejs/plugin-react'
export default defineConfig({
plugins: [react()],
test: {
environment: 'jsdom',
// ← Fuerza el modo test de React
env: {
NODE_ENV: 'test',
},
},
})
```
Por qué importa: el build de desarrollo de React incluye utilidades de test, y el build de producción las elimina. Sin `NODE_ENV: 'test'`, React se carga incorrectamente en Vercel.
### Problema 2: restricciones de recursos
Los contenedores de CI son más lentos. Operaciones que parecen instantáneas en local hacen timeout en Vercel.
La solución:
```typescript
// Configuración de timeout consciente del CI
const TIMEOUT = process.env.CI ? 10000 : 5000
it('test intensivo en recursos', async () => {
// código del test
}, TIMEOUT)
```
Una medición real de esta sesión de depuración:
```typescript
// Creando un archivo de test de 100MB
const largeFile = createMockImageFile(
'large.jpg',
100 * 1024 * 1024,
'image/jpeg'
)
// Local: ~500ms
// Vercel CI: ~6-7 segundos (!)
```
## La configuración mínima que funciona
```typescript
// vitest.config.ts
import { defineConfig } from 'vitest/config'
import react from '@vitejs/plugin-react'
import tsconfigPaths from 'vite-tsconfig-paths'
export default defineConfig({
plugins: [tsconfigPaths(), react()],
test: {
environment: 'jsdom',
setupFiles: ['./src/test/setup.ts'],
globals: true,
css: true,
// Crítico para CI de Vercel
env: {
NODE_ENV: 'test',
},
// Timeout global con conciencia de CI
testTimeout: process.env.CI ? 10000 : 5000,
},
})
```
### Timeouts de test conscientes del entorno
```typescript
// test-config.ts
export const TEST_TIMEOUTS = {
FAST: process.env.CI ? 5000 : 2000,
MEDIUM: process.env.CI ? 10000 : 5000,
SLOW: process.env.CI ? 30000 : 15000,
}
// En tus tests
import { TEST_TIMEOUTS } from './test-config'
describe('Feature', () => {
it('operación rápida', async () => {
// Test unitario rápido
}, TEST_TIMEOUTS.FAST)
it('operación de I/O de archivos', async () => {
// Procesamiento de archivos, datos pequeños
}, TEST_TIMEOUTS.MEDIUM)
it('operación compleja', async () => {
// Archivos grandes, red, procesamiento pesado
}, TEST_TIMEOUTS.SLOW)
})
```
## La checklist de diagnóstico para la próxima vez
Cuando los tests fallan en Vercel pero pasan en local:
1. Comprueba que `NODE_ENV: 'test'` está configurado en `vitest.config`
2. Lee los logs de build de Vercel buscando tests lentos
3. Añade timeouts explícitos a los tests intensivos en recursos
4. Usa configuración consciente del entorno
5. Mockea las operaciones costosas (I/O de archivos, datos grandes)
6. No empieces asumiendo que es incompatibilidad de librerías
### Patrones comunes
```typescript
// ❌ Asume entorno local
it('test', async () => {
await heavyOperation()
})
// ✅ Considera diferencias de CI
it('test', async () => {
await heavyOperation()
}, process.env.CI ? 15000 : 5000)
```
```typescript
// ❌ Creando archivos reales de 100MB
const largeFile = createRealFile(100 * 1024 * 1024)
// ✅ Usa mocks ligeros
const largeFile = createMockFile({ size: 100 * 1024 * 1024 })
```
## Lo que me enseñaron cuatro horas perdidas
### 1. El CI de Vercel no es tu MacBook
Diseña los tests con el CI en mente desde el principio: builds containerizados, recursos compartidos, I/O más lento, defaults diferentes.
### 2. Configura explícitamente
No confíes en el comportamiento por defecto. Configura `NODE_ENV` explícitamente, pon timeouts a las operaciones lentas, haz las configuraciones conscientes del entorno.
### 3. Los mensajes de error pueden engañar
`actImplementation is not a function` parecía un problema de compatibilidad de React. La causa real: React cargándose en el modo incorrecto por una mala configuración del entorno.
### 4. Diseña para CI desde el inicio
Escribe los tests sabiendo que se ejecutarán en infraestructura más lenta. Cuenta con arranques en frío de contenedores, almacenamiento en red, throttling de recursos y CPU y memoria compartidas.
## Qué hace diferente al entorno de build de Vercel
**Builds containerizados.** Cada build se ejecuta en un contenedor aislado. Los contenedores comparten recursos de infraestructura y el I/O es en red, no local.
**Arranques en frío.** Los contenedores se inician frescos en cada build. Sin caché de filesystem caliente, dependencias descargadas cada vez.
**Límites de recursos.** Throttling de CPU/memoria, infraestructura compartida, características de rendimiento diferentes.
**Variables de entorno.** Defaults diferentes a tu `.env` local. `NODE_ENV` puede no ser lo que esperas, así que configúralo explícitamente.
## Configúralo. No luches contra él.
El CI de Vercel es más lento que tu máquina (5-10x), ejecuta Node.js de otra manera y necesita configuración explícita para portarse bien.
El mensaje de error apuntaba a React. El problema era el entorno de Vercel. Saber distinguirlos es todo el arreglo, y es un cambio de una línea en la config una vez que dejas de parchear los internals de React.
## Fuentes
- [Configuración de Entorno de Vitest](https://vitest.dev/config/#environment)
- [Configuración de Build de Vercel](https://vercel.com/docs/build-step)
- [Mejores Prácticas de Testing en Next.js](https://nextjs.org/docs/testing)
**Lectura relacionada:** otra tarde perdida porque una herramienta ignoraba mi configuración en silencio: [el `content.config.ts` mal colocado que se comió mis campos de schema en Astro](/blog/astro-ubicacion-content-config/).
---
**P.D.** ¿Has librado tu propia batalla con el CI de Vercel? Cuéntame qué decía el mensaje de error y cuál era el problema de verdad, en [Twitter/X](https://x.com/garbarok).