Forem: Gustavo Ramirez

Migración de SPA a SSR híbrido en AWS, un caso real con números

Gustavo Ramirez — Tue, 10 Mar 2026 14:00:00 +0000

Este es el último artículo del arco que empecé hace casi un año. Empecé hablando de arquitectura teórica de SSR en AWS, pasé por cada framework y patrón, y ahora cierro con un caso real completo. Un proyecto que migré de Angular SPA a Next.js SSR híbrido, con los números de antes y después, los problemas que no vi venir, y las decisiones que tomaría distinto hoy.

El proyecto es una plataforma SaaS B2B con dashboards, catálogo público de productos, blog, y área autenticada. Cambié nombres y ocultando detalles de negocio, pero los números son reales.

El punto de partida

La app original era Angular 15, SPA pura, desplegada en S3 + CloudFront. Un bundle de 1.8MB gzipped, con 340 componentes, Ngrx para estado, y un API Gateway + Lambda como backend. Funcionaba, pero tenía tres problemas serios.

Primero, el SEO era catastrófico. Las páginas públicas (catálogo, blog, landing) no rankeaban. Google Search Console mostraba que el bot cargaba el HTML vacío y se iba antes de que Angular hidratara. Pagábamos Ads para tráfico que deberíamos estar ganando orgánicamente.

Segundo, el LCP estaba en 4.2 segundos en 4G mobile según CloudWatch RUM. Core Web Vitals en rojo para el 60% de usuarios. Nuestro competidor directo cargaba en 1.3 segundos y nos comía almuerzo en rankings.

Tercero, el TTI era 5.8 segundos. Los dashboards autenticados mostraban skeleton loaders durante casi 6 segundos mientras bajaba el bundle, hidratación, y las requests iniciales al API. Los usuarios enterprise se quejaban.

flowchart TD
    A[Usuario navega] --> B[CloudFront sirve index.html vacío]
    B --> C[Navegador descarga bundle Angular 1.8MB]
    C --> D[Parse y execute JS]
    D --> E[Angular bootstrap]
    E --> F[Router resuelve ruta]
    F --> G[Componente hace fetch al API]
    G --> H[Render con datos]

    style B fill:#f99
    style C fill:#f99
    style G fill:#f99

Cada paso con color rojo es latencia en la ruta crítica antes de que el usuario vea algo útil.

La decisión: Next.js + App Router + Amplify Gen 2

Evalué tres caminos. Angular Universal con SSR, quedarme en Angular pero meter prerendering estático, o migrar a Next.js.

Angular Universal era el camino de menor fricción para el equipo (3 devs Angular senior), pero el soporte en AWS Amplify era inestable cuando empecé. Tuve que desplegar Angular 18 SSR manualmente varias veces y nunca logré que el streaming funcionara bien.

Prerendering estático servía solo para las páginas públicas, no para los dashboards autenticados. Dejaba el problema de TTI intacto.

Next.js con App Router resolvía todo, pero implicaba reescribir la app y retrainar al equipo. Mi argumento al CTO del cliente fue que el costo de la migración se pagaba con los leads orgánicos recuperados en 8 meses. Le creyeron y arrancamos.

flowchart LR
    subgraph "Antes - SPA"
      A1[Angular 15]
      A2[Ngrx]
      A3[340 componentes]
      A4[S3 estático]
    end

    subgraph "Después - SSR híbrido"
      B1[Next.js 15]
      B2[Server Components]
      B3[Zustand + SWR]
      B4[Amplify Gen 2 Lambda]
    end

    A1 --> B1
    A2 --> B3
    A3 --> B2
    A4 --> B4

La estrategia de migración

Migrar 340 componentes de un golpe era suicida. Dividimos en fases.

Fase 1 (semanas 1-4): Páginas públicas. Catálogo, blog, landing pages, registro y login. El 80% del tráfico orgánico. Las reescribí en Next.js con Server Components casi 100%, solo interactividad mínima con Client Components. SEO recuperado casi inmediatamente.

Fase 2 (semanas 5-10): Shell autenticado. Login flow, navegación, layout del dashboard, gestión de cuenta y settings. Todavía con rutas Angular activas vía iframe para el dashboard principal, pero el shell completo era Next.js.

Fase 3 (semanas 11-18): Dashboards. El core de la app. Reescribimos 5 dashboards principales de Angular a Next.js, manteniendo Angular corriendo para los dashboards secundarios menos críticos.

Fase 4 (semanas 19-24): Cleanup. Migración de los dashboards restantes o decisión de retirarlos si tenían poco uso. Retiro del código Angular.

Para servir ambas apps en paralelo durante la migración, usé CloudFront con path-based routing:

// amplify/backend.ts
import { defineBackend } from "@aws-amplify/backend";
import { Distribution, CachePolicy } from "aws-cdk-lib/aws-cloudfront";
import { HttpOrigin, S3Origin } from "aws-cdk-lib/aws-cloudfront-origins";
import { Bucket } from "aws-cdk-lib/aws-s3";

const backend = defineBackend({});

const angularBucket = Bucket.fromBucketName(
  backend.createStack("LegacyStack"),
  "LegacyAngularBucket",
  "legacy-angular-app"
);

const distribution = new Distribution(
  backend.createStack("CloudFrontStack"),
  "Distribution",
  {
    defaultBehavior: {
      origin: new HttpOrigin(process.env.NEXTJS_LAMBDA_URL!),
      cachePolicy: CachePolicy.CACHING_DISABLED,
    },
    additionalBehaviors: {
      "/legacy/*": {
        origin: new S3Origin(angularBucket),
        cachePolicy: CachePolicy.CACHING_OPTIMIZED,
      },
      "/legacy-api/*": {
        origin: new HttpOrigin("old-api.internal.company.com"),
        cachePolicy: CachePolicy.CACHING_DISABLED,
      },
    },
  }
);

Todas las rutas nuevas iban a Next.js. Las rutas /legacy/* iban al Angular viejo. Durante la transición, los enlaces internos desde Next.js apuntaban a /legacy/dashboard/reports para mantener funcionalidad sin bloquear el user flow.

El reuso del API

No migré el backend. El API Gateway + Lambda Angular original siguió sirviendo ambas apps. Desde Next.js lo consumía como fetch desde Server Components:

// lib/api.ts
import { cache } from "react";
import { cookies } from "next/headers";

const API_URL = process.env.INTERNAL_API_URL!;

export const getProducts = cache(async (category?: string) => {
  const cookieStore = await cookies();
  const session = cookieStore.get("session")?.value;

  const url = new URL(`${API_URL}/products`);
  if (category) url.searchParams.set("category", category);

  const res = await fetch(url, {
    headers: session ? { Authorization: `Bearer ${session}` } : {},
    next: { revalidate: 60, tags: ["products"] },
  });

  if (!res.ok) throw new Error("Failed to fetch products");
  return res.json() as Promise<Product[]>;
});

El cache() de React deduplica calls dentro de la misma request. Si tres componentes piden productos, solo una request real al API sale. El next: { revalidate: 60 } cachea la respuesta por 60 segundos entre requests.

Este patrón me permitió migrar sin tocar el backend, que era el 70% del código del proyecto.

Server Components para el catálogo

El catálogo era la página más importante para SEO. Antes, Angular bajaba el bundle y hacía fetch al API. Ahora, Server Components renderizan el HTML completo en Lambda:

// app/catalog/[category]/page.tsx
import { getProducts, getCategory } from "@/lib/api";
import { notFound } from "next/navigation";
import { ProductGrid } from "./product-grid";
import { FilterSidebar } from "./filter-sidebar";

export async function generateMetadata({
  params,
}: {
  params: Promise<{ category: string }>;
}) {
  const { category } = await params;
  const cat = await getCategory(category);

  if (!cat) return { title: "Categoría no encontrada" };

  return {
    title: `${cat.name} | MiTienda`,
    description: cat.description,
    openGraph: {
      title: cat.name,
      description: cat.description,
      images: [cat.imageUrl],
    },
  };
}

export default async function CategoryPage({
  params,
  searchParams,
}: {
  params: Promise<{ category: string }>;
  searchParams: Promise<{ sort?: string; page?: string }>;
}) {
  const { category } = await params;
  const { sort = "popular", page = "1" } = await searchParams;

  const [cat, products] = await Promise.all([
    getCategory(category),
    getProducts(category, { sort, page: parseInt(page) }),
  ]);

  if (!cat) notFound();

  return (
    <div className="container mx-auto grid grid-cols-12 gap-6">
      <aside className="col-span-3">
        <FilterSidebar category={cat} />
      </aside>
      <main className="col-span-9">
        <h1 className="text-3xl font-bold mb-6">{cat.name}</h1>
        <ProductGrid products={products} />
      </main>
    </div>
  );
}

ProductGrid es Server Component. Los filtros son Client Component porque tienen estado interactivo, pero el HTML inicial tiene todos los productos renderizados. Google bot ve una página completa.

El dashboard autenticado: streaming

Para los dashboards, usé streaming con Suspense. El shell del dashboard se renderiza instantáneo, los widgets pesados cargan progresivamente:

// app/dashboard/page.tsx
import { Suspense } from "react";
import { MetricsWidget } from "./metrics-widget";
import { RevenueChart } from "./revenue-chart";
import { RecentOrders } from "./recent-orders";
import { WidgetSkeleton } from "./skeletons";

export default function DashboardPage() {
  return (
    <div className="grid grid-cols-12 gap-4 p-6">
      <section className="col-span-12">
        <h1 className="text-2xl font-bold">Dashboard</h1>
      </section>

      <section className="col-span-4">
        <Suspense fallback={<WidgetSkeleton />}>
          <MetricsWidget />
        </Suspense>
      </section>

      <section className="col-span-8">
        <Suspense fallback={<WidgetSkeleton />}>
          <RevenueChart />
        </Suspense>
      </section>

      <section className="col-span-12">
        <Suspense fallback={<WidgetSkeleton />}>
          <RecentOrders />
        </Suspense>
      </section>
    </div>
  );
}

Cada widget hace su propio fetch async. El usuario ve el layout inmediatamente, y cada widget aparece cuando sus datos terminan de cargar. La sensación es mucho más rápida aunque el tiempo total sea similar.

Los números: antes vs después

Mediciones tomadas con CloudWatch RUM, sampling 100%, comparando el mes anterior a la migración contra el mes posterior a completar fase 3.

Métrica	Antes (Angular SPA)	Después (Next.js SSR)	Cambio
LCP p75 mobile	4.2s	1.4s	-67%
FCP p75 mobile	2.8s	0.6s	-79%
TTI p75 mobile	5.8s	2.1s	-64%
Bundle size (homepage)	1.8MB	180KB	-90%
Bounce rate	58%	34%	-41%
Orgánico mensual	12,400 sesiones	38,700 sesiones	+212%
Conversión signup	2.1%	3.8%	+81%
CloudFront egress	2.3 TB/mes	0.9 TB/mes	-61%
Lambda costs	$180/mes	$340/mes	+88%
Total infra	$1,240/mes	$1,180/mes	-5%

El costo Lambda subió porque ahora cada request hace trabajo server-side. Pero el ahorro en egress de CloudFront (bundle más pequeño, imágenes optimizadas) compensó. El total de infra bajó 5%.

El número que convenció a negocios fue el orgánico. Pasamos de 12K a 38K sesiones mensuales orgánicas en 6 meses post-migración, y el equipo de marketing pudo reducir gasto de Ads en 40% manteniendo leads constantes.

Lo que no vi venir

1. El cache de CloudFront quedó obsoleto agresivamente.
Next.js genera hashes nuevos en cada deploy para JS y CSS. Con deploys diarios, CloudFront invalidaba cache constantemente. Resolví con cache policy que respeta los headers Cache-Control: immutable de los assets hasheados. El HTML dinámico no se cachea, pero los assets sí por un año.

2. Server Components no pueden usar hooks de cliente, obvio, pero arrastró re-writes inesperados.
Cada librería que internamente usa React context se vuelve cliente. Mi librería de forms (react-hook-form) obligó a que todos los formularios sean client. Eso rompió mi plan inicial de tener forms server-rendered con progressive enhancement. Tuve que migrar forms a native HTML + Server Actions, lo que resultó siendo mejor.

3. El equipo batalló con el modelo mental.
Tres devs Angular llevaron 2 meses en estar cómodos con el modelo de Server Components vs Client Components. Los errores típicos: intentar usar useState en server component, pasar funciones como props cross-boundary, olvidar "use client" al tope. Hice workshops internos y documenté patrones comunes.

4. El monitoring cambió completamente.
En SPA, el performance era 100% browser-side. En SSR, la mitad del tiempo se gasta en Lambda. Agregué X-Ray con Datadog para trackear el pipeline completo: CloudFront -> Lambda -> API interno -> DB -> Lambda return -> CloudFront. Los primeros meses tuvimos bugs sutiles de latencia que solo se vieron con trazas distribuidas.

5. El fallback sin JS reveló bugs antiguos.
Probar Server Actions sin JavaScript descubrió que varios formularios viejos dependían en eventos onBlur para validación, que no se disparan en submit nativo. Refactoricé todo a validación server-side con zod.

6. Amplify Gen 2 todavía tiene bugs raros.
Hubo al menos tres deploys donde el build pasó pero la aplicación no arrancó en Lambda por issues con el runtime de Node. Tuve que fijar versiones en package.json y específicamente en engines. Desde entonces estable, pero me costó algunos incidentes.

7. La autenticación fue la parte más difícil.
Mover de auth client-side (token en localStorage) a server-side (cookies httpOnly) implicó reescribir todo el flow. Costos de sesión, refresh tokens, logout cross-device. Ver artículo 13 de este arco para detalles.

Lo que haría distinto

Si empezara hoy, optimizaría tres decisiones.

Primero, no mantendría CloudFront path-based routing tanto tiempo. Nos quedamos 4 meses con Angular legacy corriendo en /legacy/*, y eso creó ambigüedad constante. Los usuarios veían URLs distintas para partes de la app, cacheo se comportaba raro, y el equipo de soporte no sabía siempre qué versión estaba el usuario usando. Hoy, migraría dashboards secundarios a Next.js aunque sean más básicos, para tener todo en un solo stack más rápido.

Segundo, invertiría en visual regression testing desde el día uno. Pasamos dos semanas cazando bugs visuales que Playwright E2E no capturaba. Percy o Chromatic desde el principio nos habría ahorrado tiempo.

Tercero, usaría RSC para contenido editorial desde el principio. Al inicio prerenderaba el blog como static, pero los clientes editaban contenido en un CMS (Strapi) y necesitaban preview inmediato. RSC con revalidateTag desde un webhook del CMS resolvió eso elegantemente. Lo adopté tarde, debí ser día uno.

El arco cierra, el trabajo sigue

Este proyecto duró 6 meses en ejecución y 8 meses en ver los resultados completos de SEO. Desde que terminamos, el cliente ha crecido 3x en usuarios sin problemas de performance. La app hoy corre en Amplify Gen 2 con cero intervención manual, deploys automáticos desde main, y el equipo original es 100% autónomo con Next.js.

Empecé este arco hace casi un año con un artículo sobre arquitectura teórica de SSR. Pasé por Next.js, Angular, Astro, Nuxt, SvelteKit, Remix, micro-frontends, edge computing, CI/CD, auth, observability, multi-region, SEO, PWAs, i18n, security headers, y finalmente Server Actions. Cada tema salió de un proyecto real.

Lo que aprendí en este proceso es que SSR en AWS no es un framework ni una herramienta. Es una forma de pensar sobre dónde ocurre el trabajo: en el browser, en el edge, o en el Lambda. Con la arquitectura correcta, pagas poco en infra y entregas experiencia premium. Con la arquitectura incorrecta, tu Lambda bill se dispara y los usuarios igual esperan 5 segundos.

Si estás arrancando una migración así, lo más importante no es elegir el framework perfecto, sino medir lo que tienes hoy y definir qué quieres lograr. Los números mandan. Los frameworks son herramientas.

Gracias a todos los que leyeron estos 30 artículos durante el año. Voy a seguir escribiendo, probablemente sobre backend distribuido en AWS a partir del próximo mes. Nos leemos.

Server Actions de Next.js en Lambda, formularios sin JavaScript

Gustavo Ramirez — Thu, 26 Feb 2026 14:00:00 +0000

Llevo un año construyendo aplicaciones con Server Actions de Next.js en producción, desplegadas en Lambda via Amplify Gen 2. Al principio las miré con escepticismo porque cada vez que Vercel saca una feature nueva pienso "genial, otra cosa que solo funciona bien en su plataforma". Pero después de migrar tres proyectos, acepto que Server Actions son genuinamente útiles, incluso fuera de Vercel.

La tesis del artículo es simple: Server Actions te dan formularios que funcionan sin JavaScript, progressive enhancement real, y menos código. En Lambda funcionan perfectamente si entiendes algunos detalles de cómo Next.js los serializa y cómo Lambda los invoca.

El problema que resuelven

Antes de Server Actions, el flujo típico de un formulario en Next.js era:

sequenceDiagram
    participant U as Usuario
    participant C as Componente Cliente
    participant A as API Route
    participant D as Base de datos

    U->>C: Envía formulario
    C->>C: preventDefault
    C->>C: Valida con zod
    C->>A: fetch POST /api/users
    A->>A: Re-valida con zod
    A->>D: Insert
    D-->>A: Resultado
    A-->>C: JSON response
    C->>C: Actualiza estado local
    C->>C: Muestra toast
    C->>C: router.refresh o mutate SWR

Hay tres problemas acá. Primero, duplicas validación en cliente y servidor. Segundo, todo depende de JavaScript cargado, ejecutándose y sin errores. Si el JS falla o tarda en cargar, el formulario no sirve. Tercero, la API Route es un endpoint HTTP que cualquiera puede llamar, así que necesitas CSRF tokens, rate limiting, y auth checks redundantes.

Server Actions eliminan la API Route intermedia:

sequenceDiagram
    participant U as Usuario
    participant F as Form (server)
    participant SA as Server Action (Lambda)
    participant D as Base de datos

    U->>F: Submit (nativo, sin JS)
    F->>SA: POST con form data serializada
    SA->>SA: Valida con zod
    SA->>D: Insert
    D-->>SA: Resultado
    SA-->>F: HTML nuevo + redirect
    F->>U: Render actualizado

Lo notable: si el usuario tiene JavaScript deshabilitado, bloqueado por una extensión, o simplemente el bundle no cargó todavía, el formulario funciona igual. Next.js hace progressive enhancement automático.

Ejemplo real: formulario de registro

Este es código de producción simplificado de un proyecto real. Es un formulario de registro para una plataforma SaaS.

// app/register/page.tsx
import { register } from "./actions";
import { SubmitButton } from "./submit-button";

export default function RegisterPage() {
  return (
    <form action={register} className="max-w-md mx-auto space-y-4">
      <h1 className="text-2xl font-bold">Crear cuenta</h1>

      <div>
        <label htmlFor="email" className="block text-sm font-medium">
          Email
        </label>
        <input
          id="email"
          name="email"
          type="email"
          required
          className="mt-1 w-full rounded border px-3 py-2"
        />
      </div>

      <div>
        <label htmlFor="password" className="block text-sm font-medium">
          Contraseña
        </label>
        <input
          id="password"
          name="password"
          type="password"
          required
          minLength={8}
          className="mt-1 w-full rounded border px-3 py-2"
        />
      </div>

      <div>
        <label htmlFor="company" className="block text-sm font-medium">
          Empresa
        </label>
        <input
          id="company"
          name="company"
          type="text"
          required
          className="mt-1 w-full rounded border px-3 py-2"
        />
      </div>

      <SubmitButton />
    </form>
  );
}

Nota que no hay onSubmit, no hay useState, no hay fetch. El action del form apunta directamente a una función server. La acción register vive en un archivo separado:

// app/register/actions.ts
"use server";

import { z } from "zod";
import { redirect } from "next/navigation";
import { cookies } from "next/headers";
import { hash } from "bcryptjs";
import { db } from "@/lib/db";
import { createSession } from "@/lib/session";
import { sendWelcomeEmail } from "@/lib/email";

const RegisterSchema = z.object({
  email: z.string().email(),
  password: z.string().min(8),
  company: z.string().min(2).max(100),
});

export async function register(formData: FormData) {
  const raw = Object.fromEntries(formData);
  const parsed = RegisterSchema.safeParse(raw);

  if (!parsed.success) {
    return {
      error: "Datos inválidos",
      fieldErrors: parsed.error.flatten().fieldErrors,
    };
  }

  const { email, password, company } = parsed.data;

  const existing = await db.user.findUnique({ where: { email } });
  if (existing) {
    return { error: "Este email ya está registrado" };
  }

  const passwordHash = await hash(password, 12);

  const user = await db.user.create({
    data: {
      email,
      passwordHash,
      company: { create: { name: company } },
    },
    include: { company: true },
  });

  const session = await createSession(user.id);
  (await cookies()).set("session", session.token, {
    httpOnly: true,
    secure: true,
    sameSite: "lax",
    maxAge: 60 * 60 * 24 * 30,
  });

  await sendWelcomeEmail(user.email, user.company.name);

  redirect("/dashboard");
}

La directiva "use server" al tope del archivo marca cada export como Server Action. Next.js genera un endpoint interno que invoca esta función cuando recibe el POST. El hash del archivo es parte de la URL, lo que protege contra invocaciones arbitrarias.

El botón con pending state

Para mostrar feedback visual mientras la acción corre, usas useFormStatus:

// app/register/submit-button.tsx
"use client";

import { useFormStatus } from "react-dom";

export function SubmitButton() {
  const { pending } = useFormStatus();

  return (
    <button
      type="submit"
      disabled={pending}
      className="w-full bg-blue-600 text-white rounded py-2 disabled:opacity-50"
    >
      {pending ? "Creando cuenta..." : "Registrarme"}
    </button>
  );
}

Este componente es cliente porque usa un hook, pero el form entero sigue funcionando sin JavaScript. Cuando JS está disponible, el botón muestra el estado pending. Cuando no, el navegador hace un submit regular y navega a la página de respuesta.

Validación con useActionState

Para mostrar errores de validación sin perder el estado del formulario, usas useActionState:

// app/register/page.tsx (versión con errores)
"use client";

import { useActionState } from "react";
import { register } from "./actions";
import { SubmitButton } from "./submit-button";

const initialState = { error: null, fieldErrors: {} };

export default function RegisterPage() {
  const [state, formAction] = useActionState(register, initialState);

  return (
    <form action={formAction} className="max-w-md mx-auto space-y-4">
      <h1 className="text-2xl font-bold">Crear cuenta</h1>

      {state.error && (
        <div className="bg-red-50 border border-red-200 text-red-700 p-3 rounded">
          {state.error}
        </div>
      )}

      <div>
        <label htmlFor="email">Email</label>
        <input
          id="email"
          name="email"
          type="email"
          required
          aria-invalid={!!state.fieldErrors?.email}
        />
        {state.fieldErrors?.email && (
          <p className="text-sm text-red-600">{state.fieldErrors.email[0]}</p>
        )}
      </div>

      {/* resto de campos */}

      <SubmitButton />
    </form>
  );
}

Cuando usas useActionState, el componente se vuelve cliente pero mantiene progressive enhancement. Sin JS, el submit sigue funcionando aunque sin mostrar los errores inline.

Cómo viajan los Server Actions a Lambda

Acá es donde la cosa se pone interesante para los que desplegamos fuera de Vercel. Cuando Next.js serializa un Server Action, genera un endpoint RPC interno. En Amplify Gen 2 con Lambda, el deploy funciona así:

flowchart LR
    A[Build Next.js] --> B[Genera manifest con action IDs]
    B --> C[Bundle Lambda handler]
    C --> D[Lambda Response Streaming]
    D --> E[CloudFront]

    F[Cliente submit] --> G[POST /register con header Next-Action]
    G --> E
    E --> D
    D --> H[Next.js server runtime]
    H --> I[Ejecuta action]
    I --> J[Retorna HTML + redirect]
    J --> F

El header clave es Next-Action: <hash>. Next.js lo usa para identificar qué función ejecutar. El Lambda handler de Amplify Gen 2 procesa este header sin modificación.

La configuración del adapter es mínima:

// amplify/backend.ts
import { defineBackend } from "@aws-amplify/backend";
import { auth } from "./auth/resource";
import { data } from "./data/resource";

const backend = defineBackend({
  auth,
  data,
});

// Amplify Gen 2 detecta Next.js automáticamente y configura el runtime
// No necesitas configurar nada específico para Server Actions

Lo único que recomiendo es aumentar el timeout del Lambda si tus actions hacen operaciones pesadas:

// next.config.ts
import type { NextConfig } from "next";

const config: NextConfig = {
  experimental: {
    serverActions: {
      bodySizeLimit: "5mb",
    },
  },
};

export default config;

El bodySizeLimit es importante. Por defecto es 1MB, lo que se queda corto si subes archivos vía Server Actions.

Upload de archivos con Server Actions

Este patrón lo uso mucho. Un formulario que sube una imagen directamente a S3:

// app/profile/avatar/actions.ts
"use server";

import { z } from "zod";
import { revalidatePath } from "next/cache";
import { S3Client, PutObjectCommand } from "@aws-sdk/client-s3";
import { getSession } from "@/lib/session";
import { db } from "@/lib/db";
import { randomUUID } from "crypto";

const s3 = new S3Client({ region: process.env.AWS_REGION });
const BUCKET = process.env.AVATARS_BUCKET!;

const AvatarSchema = z.object({
  file: z
    .instanceof(File)
    .refine((f) => f.size < 5 * 1024 * 1024, "Máximo 5MB")
    .refine(
      (f) => ["image/jpeg", "image/png", "image/webp"].includes(f.type),
      "Solo JPG, PNG o WebP"
    ),
});

export async function uploadAvatar(formData: FormData) {
  const session = await getSession();
  if (!session) return { error: "No autenticado" };

  const parsed = AvatarSchema.safeParse({ file: formData.get("file") });
  if (!parsed.success) {
    return { error: parsed.error.errors[0].message };
  }

  const { file } = parsed.data;
  const buffer = Buffer.from(await file.arrayBuffer());
  const key = `avatars/${session.userId}/${randomUUID()}.${file.type.split("/")[1]}`;

  await s3.send(
    new PutObjectCommand({
      Bucket: BUCKET,
      Key: key,
      Body: buffer,
      ContentType: file.type,
      CacheControl: "public, max-age=31536000, immutable",
    })
  );

  await db.user.update({
    where: { id: session.userId },
    data: { avatarKey: key },
  });

  revalidatePath("/profile");
  return { success: true, key };
}

El formulario correspondiente:

// app/profile/avatar/form.tsx
"use client";

import { useActionState } from "react";
import { uploadAvatar } from "./actions";

export function AvatarForm() {
  const [state, action] = useActionState(uploadAvatar, null);

  return (
    <form action={action} encType="multipart/form-data">
      <input type="file" name="file" accept="image/*" required />
      <button type="submit">Subir avatar</button>
      {state?.error && <p className="text-red-600">{state.error}</p>}
      {state?.success && <p className="text-green-600">Avatar actualizado</p>}
    </form>
  );
}

El encType="multipart/form-data" es crítico. Sin él, el archivo llega como string vacío.

Optimistic updates con useOptimistic

Para UX pulida, combina Server Actions con useOptimistic:

// app/tasks/task-list.tsx
"use client";

import { useOptimistic, useTransition } from "react";
import { toggleTask, deleteTask } from "./actions";

type Task = { id: string; title: string; done: boolean };

export function TaskList({ tasks }: { tasks: Task[] }) {
  const [optimisticTasks, updateOptimistic] = useOptimistic(
    tasks,
    (state, action: { type: string; id: string; done?: boolean }) => {
      if (action.type === "toggle") {
        return state.map((t) =>
          t.id === action.id ? { ...t, done: action.done! } : t
        );
      }
      if (action.type === "delete") {
        return state.filter((t) => t.id !== action.id);
      }
      return state;
    }
  );

  const [, startTransition] = useTransition();

  return (
    <ul>
      {optimisticTasks.map((task) => (
        <li key={task.id} className="flex items-center gap-2">
          <input
            type="checkbox"
            checked={task.done}
            onChange={(e) => {
              startTransition(async () => {
                updateOptimistic({
                  type: "toggle",
                  id: task.id,
                  done: e.target.checked,
                });
                await toggleTask(task.id, e.target.checked);
              });
            }}
          />
          <span className={task.done ? "line-through" : ""}>{task.title}</span>
          <form
            action={async () => {
              startTransition(async () => {
                updateOptimistic({ type: "delete", id: task.id });
                await deleteTask(task.id);
              });
            }}
          >
            <button type="submit">Eliminar</button>
          </form>
        </li>
      ))}
    </ul>
  );
}

El checkbox actualiza el UI antes de que el Server Action retorne. Si falla, React revierte automáticamente al estado del servidor.

Revalidación granular

Server Actions se integran con el cache de Next.js. Después de mutar datos, revalidas rutas o tags específicos:

// app/posts/actions.ts
"use server";

import { revalidateTag, revalidatePath } from "next/cache";
import { db } from "@/lib/db";

export async function createPost(formData: FormData) {
  const title = formData.get("title") as string;
  const body = formData.get("body") as string;

  const post = await db.post.create({ data: { title, body } });

  revalidateTag(`posts`);
  revalidatePath(`/posts`);

  return { id: post.id };
}

export async function updatePost(id: string, formData: FormData) {
  const title = formData.get("title") as string;
  const body = formData.get("body") as string;

  await db.post.update({ where: { id }, data: { title, body } });

  revalidateTag(`post-${id}`);
  revalidatePath(`/posts/${id}`);
}

Y en el componente que consume:

// app/posts/[id]/page.tsx
import { unstable_cache } from "next/cache";
import { db } from "@/lib/db";

async function getPost(id: string) {
  return unstable_cache(
    async () => db.post.findUnique({ where: { id } }),
    [`post-${id}`],
    { tags: [`post-${id}`] }
  )();
}

export default async function PostPage({
  params,
}: {
  params: Promise<{ id: string }>;
}) {
  const { id } = await params;
  const post = await getPost(id);

  return (
    <article>
      <h1>{post?.title}</h1>
      <p>{post?.body}</p>
    </article>
  );
}

Cuando llamas revalidateTag('post-123'), Next.js invalida el cache solo para ese post. Próxima request regenera solo esa página.

Comparación: API Route vs Server Action

Aspecto	API Route	Server Action
Funciona sin JS	No	Sí
Código duplicado de validación	Sí (cliente + server)	No (solo server)
Protección CSRF	Manual	Automática (origin check)
Tipo-safety extremo a extremo	Manual con tRPC o similar	Nativa
Upload de archivos	Manual con FormData	Nativo
Integración con cache	Manual (revalidatePath)	Nativa
Funciona como RPC externo	Sí	No (solo desde la app)
Debugging	Network tab estándar	Header `Next-Action`, más opaco

El trade-off principal es que los Server Actions son internos. No puedes llamarlos desde una app móvil o un script externo. Para eso sigues necesitando API Routes o AppSync.

Lo que aprendí en producción

1. Cold starts matan si haces imports pesados en el mismo archivo.
Mi primer error fue poner import { PrismaClient } from "@prisma/client" en un archivo con muchas Server Actions. Cada cold start de Lambda cargaba Prisma entero, que pesa 30MB con el client generado. Moví Prisma a un singleton en /lib/db.ts y uso import { db } donde lo necesito. Bundle analyzer confirma que ahora cada action pesa menos de 500KB.

2. Las actions no pueden retornar clases ni funciones.
Next.js serializa el return value para pasarlo al cliente. Solo funciona con datos planos: strings, numbers, booleans, arrays, objects, Dates. Un día retorné una instancia de un error custom y todo se rompió silenciosamente. Ahora siempre retorno { success: boolean, data?: ..., error?: string }.

3. cookies() y headers() son async desde Next 15.
Migrando proyectos viejos, me pegué contra esto muchas veces. Si ves warnings tipo "cookies() should be awaited", agregas el await. TypeScript a veces no los detecta porque los types cambiaron.

4. CSRF está cubierto pero no para cross-origin.
Server Actions validan el header Origin contra el host. Si tienes un dominio embebido en iframes de otros dominios legítimos (tipo embedded widgets), necesitas configurar allowedOrigins en next.config.ts. Si no, las requests fallarán con error genérico.

5. El Lambda timeout es tu enemigo.
Por defecto Amplify Gen 2 pone Lambda con 30 segundos. Si tu Server Action hace algo largo, tipo procesar CSV grande, te cortan. Para esos casos, la action solo encola un job en SQS y retorna. El procesamiento real corre en un Lambda separado, y notificas al usuario vía WebSocket o polling.

Cuándo NO usar Server Actions

Si necesitas un endpoint consumible por terceros, Server Actions no sirven porque la URL es interna y cambia con cada build. Usa API Routes o AppSync.

Si tu app es puramente cliente (extensión de Chrome, Electron, mobile), no puedes usar Server Actions porque no hay servidor Next.js corriendo. Mantén API Routes.

Si tu action es extremadamente sensible en performance y haces 100 por segundo, considera que cada Server Action tiene overhead de React Server Rendering en el return. Para alta frecuencia, una API Route minimal puede ser 3 o 4 veces más rápida.

Si el equipo no conoce React Server Components, adoptar Server Actions sin entender el modelo mental es receta para bugs. Primero aseguren que entienden la separación cliente/servidor.

El próximo artículo cierra el arco. Un caso real de migración de SPA pura a SSR híbrido en AWS, con los números reales de performance, costos y las decisiones que tomé en el camino.

AWS CDK Migrate como converti un CloudFormation legacy a CDK en un dia

Gustavo Ramirez — Thu, 19 Feb 2026 14:00:00 +0000

cdk migrate es un comando que salió hace un tiempo y que muchos no conocen. Convierte CloudFormation existente a código CDK. Lo usé hace poco en un proyecto heredado y quiero contar cómo me fue.

El escenario

Heredé un stack de CloudFormation de unas 800 líneas de YAML. Funcionaba, pero cada cambio tomaba mucho tiempo porque nadie quería tocar el archivo. El equipo decidió migrar a CDK para poder usar TypeScript y separar responsabilidades.

El comando

cdk migrate \
  --stack-name mi-stack-legacy \
  --from-stack \
  --language typescript

Esto toma el stack desplegado, descarga su plantilla, y genera código CDK equivalente.

Lo que genera

Un proyecto CDK completo con un stack que replica exactamente lo que había. No es código bonito. Es código funcional que refleja la estructura del YAML original.

Lo que hice después

Refactoricé por responsabilidad. El stack monolítico lo partí en tres: red, datos, cómputo.
Reemplacé recursos L1 por L2. CDK migrate genera muchos CfnX crudos porque es la traducción más segura. Los cambié por constructs L2 cuando tenía sentido.
Agregué tests. Usando aws-cdk-lib/assertions para validar que la estructura se mantenía.
Hice cdk diff. Este paso es crítico. Me aseguró que mi código nuevo generaba exactamente el mismo CloudFormation que el stack existente. Cero cambios de drift.

El paso que no te puedes saltar

Antes de hacer cdk deploy por primera vez sobre el stack migrado, toca importar los recursos. CDK migrate te da las instrucciones, pero resumido:

Despliegas el nuevo stack CDK en modo "resource import".
Asocia los recursos existentes al nuevo stack.
Eliminas el stack viejo sin tocar los recursos.

Este paso lo probé primero en un ambiente de pruebas. No lo hagas directo en producción sin ensayar.

Lo que no migra bien

Recursos con nombres autogenerados son un dolor porque hay que preservar el nombre.
Outputs que otros stacks consumen requieren cuidado extra.
Custom resources con Lambdas asociadas a veces necesitan retoque manual.

Cierre

cdk migrate no es mágico, pero es un punto de partida decente. Te ahorra escribir desde cero el esqueleto del stack y puedes concentrarte en el refactor, que es donde está el valor real.

Rate limiting en edge con CloudFront y DynamoDB Global Tables

Gustavo Ramirez — Sat, 14 Feb 2026 14:00:00 +0000

Un lunes a las 3am me despertó una alerta. El API de un cliente estaba caído porque alguien estaba scrapeando el catálogo de productos a 800 requests por segundo desde una IP. El Lambda de Next.js estaba saturado, cold starts por todos lados, usuarios reales viendo errores 503. Resolví ese día con un AWS WAF rápido, pero supe que necesitaba algo mejor: rate limiting en el edge, antes de que el tráfico llegue al origin.

Este artículo cubre el diseño que implementé después: rate limiting distribuido usando Lambda@Edge + DynamoDB Global Tables. Funciona cerca del usuario, respeta límites por IP y por usuario autenticado, y no mete latencia a requests legítimos. El costo operacional es bajo y la protección es real.

Las opciones y por qué elegí la que elegí

AWS tiene tres formas principales de hacer rate limiting antes del origin. Cada una tiene trade-offs:

AWS WAF Rate-based Rules.
El más simple. Configuras una regla tipo "bloquear IPs que hagan más de 2000 requests en 5 minutos". Funciona out-of-the-box con CloudFront. El problema: el mínimo es 100 requests en 5 minutos y la ventana es fija de 5 minutos (desde hace poco 1 minuto también). No puedes hacer rate limiting por user ID ni por endpoint específico con granularidad fina.

API Gateway Throttling.
Si tu tráfico pasa por API Gateway, tiene throttling nativo por API key o por ruta. Funciona bien pero no aplica si estás usando CloudFront directo a Lambda o S3. Y no hace rate limiting por usuario autenticado sin pegarse con API Gateway custom authorizers.

Lambda@Edge con storage distribuido.
Más complejo pero más poderoso. Interceptas cada request, consultas un store para saber si el cliente ya superó su límite, decides si rechazar o pasar. El store puede ser DynamoDB, ElastiCache, lo que quieras.

Elegí Lambda@Edge porque necesitaba rate limiting diferenciado: IPs anónimas tienen límites bajos, usuarios autenticados tienen límites más altos, y rutas caras (como reports) tienen límites más agresivos que rutas baratas.

flowchart TB
    U[Usuario] --> CF[CloudFront]
    CF --> LE[Lambda@Edge viewer-request]
    LE --> DDB[DynamoDB Global Table]
    DDB -->|Contador actualizado| LE
    LE -->|Allow| O[Origin: Lambda Next.js]
    LE -->|Block 429| R[Response rechazada]
    LE -->|Challenge| C[CAPTCHA page]

El modelo en DynamoDB

Cada entrada es un contador por clave (IP o user) y ventana temporal. Uso ventanas deslizantes de 60 segundos como default.

PK (cliente + ruta)	SK (timestamp ventana)	count	ttl
`IP#1.2.3.4#PATH#/api/reports`	`202602141430`	45	1739556600
`USER#u_abc#PATH#/api/reports`	`202602141430`	120	1739556600
`IP#1.2.3.4#PATH#global`	`202602141430`	180	1739556600

El ttl de DynamoDB borra automáticamente entradas viejas después de 1 hora. Sin mantenimiento manual.

Global Tables es importante porque Lambda@Edge corre en múltiples regiones. Si usas DynamoDB en una sola región, todos los reads/writes desde edge locations de Asia tienen que viajar hasta (digamos) us-east-1. Global Tables replica la tabla en las regiones que elijas y cada Lambda@Edge lee de su réplica local.

CDK para la tabla global

// cdk/lib/rate-limit-stack.ts
import { Stack, StackProps } from "aws-cdk-lib";
import {
  TableV2,
  AttributeType,
  Billing,
  ReplicaGlobalSecondaryIndexOptions,
} from "aws-cdk-lib/aws-dynamodb";
import { Construct } from "constructs";

export class RateLimitStack extends Stack {
  public readonly tableName: string;

  constructor(scope: Construct, id: string, props?: StackProps) {
    super(scope, id, props);

    const table = new TableV2(this, "RateLimitTable", {
      tableName: "rate-limits",
      partitionKey: { name: "PK", type: AttributeType.STRING },
      sortKey: { name: "SK", type: AttributeType.STRING },
      timeToLiveAttribute: "ttl",
      billing: Billing.onDemand(),
      replicas: [
        { region: "eu-west-1" },
        { region: "ap-southeast-1" },
        { region: "sa-east-1" },
      ],
    });

    this.tableName = table.tableName;
  }
}

Defino us-east-1 como región principal (donde vive Lambda@Edge siempre) y replicas en Europa, Asia y Sudamérica. El costo de replicación es real: pagas por writes en cada región. Pero el beneficio de latencia baja en cada edge compensa para este caso de uso.

El Lambda@Edge

// lambda-edge/rate-limit/index.ts
import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
import {
  UpdateCommand,
  DynamoDBDocumentClient,
} from "@aws-sdk/lib-dynamodb";
import type { CloudFrontRequestEvent, CloudFrontRequestResult } from "aws-lambda";

const client = new DynamoDBClient({
  region: process.env.AWS_REGION, // Lambda@Edge corre en la región más cercana al POP
});
const doc = DynamoDBDocumentClient.from(client);
const TABLE = "rate-limits";

type Limits = { perMinute: number; perPath?: Record<string, number> };

const LIMITS: Record<"anonymous" | "authenticated", Limits> = {
  anonymous: {
    perMinute: 60,
    perPath: {
      "/api/reports": 5,
      "/api/export": 3,
      "/api/search": 30,
    },
  },
  authenticated: {
    perMinute: 300,
    perPath: {
      "/api/reports": 30,
      "/api/export": 20,
      "/api/search": 120,
    },
  },
};

export const handler = async (
  event: CloudFrontRequestEvent
): Promise<CloudFrontRequestResult> => {
  const request = event.Records[0].cf.request;
  const ip = request.clientIp;
  const uri = request.uri;
  const userId = extractUserId(request);

  const tier = userId ? "authenticated" : "anonymous";
  const identity = userId ? `USER#${userId}` : `IP#${ip}`;

  // Ventana de 60 segundos, redondeada
  const windowTs = Math.floor(Date.now() / 60000);
  const windowKey = windowTs.toString();
  const ttl = windowTs * 60 + 300; // mantener 5 min para debugging

  // Checar límite específico por path si existe
  const pathLimit = matchPathLimit(uri, LIMITS[tier]);
  if (pathLimit) {
    const result = await incrementAndCheck(
      `${identity}#PATH#${pathLimit.path}`,
      windowKey,
      pathLimit.limit,
      ttl
    );
    if (!result.allowed) return rateLimitResponse(result, pathLimit.limit);
  }

  // Checar límite global
  const globalResult = await incrementAndCheck(
    `${identity}#PATH#global`,
    windowKey,
    LIMITS[tier].perMinute,
    ttl
  );
  if (!globalResult.allowed) {
    return rateLimitResponse(globalResult, LIMITS[tier].perMinute);
  }

  // Pasar headers con info del rate limit para el origin
  request.headers["x-rate-limit-remaining"] = [
    { key: "X-RateLimit-Remaining", value: String(globalResult.remaining) },
  ];

  return request;
};

async function incrementAndCheck(
  pk: string,
  sk: string,
  limit: number,
  ttl: number
): Promise<{ allowed: boolean; count: number; remaining: number }> {
  try {
    const result = await doc.send(
      new UpdateCommand({
        TableName: TABLE,
        Key: { PK: pk, SK: sk },
        UpdateExpression:
          "ADD #c :one SET #t = if_not_exists(#t, :ttl)",
        ExpressionAttributeNames: { "#c": "count", "#t": "ttl" },
        ExpressionAttributeValues: {
          ":one": 1,
          ":ttl": ttl,
        },
        ReturnValues: "UPDATED_NEW",
      })
    );

    const count = Number(result.Attributes?.count ?? 1);
    return {
      allowed: count <= limit,
      count,
      remaining: Math.max(0, limit - count),
    };
  } catch (err) {
    // Si DynamoDB falla, dejamos pasar para no bloquear tráfico legítimo
    console.error("Rate limit check failed:", err);
    return { allowed: true, count: 0, remaining: limit };
  }
}

function extractUserId(request: any): string | null {
  // Asume que un Lambda@Edge anterior (auth) validó el JWT y puso el user ID en header
  return request.headers["x-user-id"]?.[0]?.value || null;
}

function matchPathLimit(
  uri: string,
  limits: Limits
): { path: string; limit: number } | null {
  if (!limits.perPath) return null;
  for (const [path, limit] of Object.entries(limits.perPath)) {
    if (uri.startsWith(path)) return { path, limit };
  }
  return null;
}

function rateLimitResponse(
  result: { count: number; remaining: number },
  limit: number
): CloudFrontRequestResult {
  return {
    status: "429",
    statusDescription: "Too Many Requests",
    headers: {
      "content-type": [{ key: "Content-Type", value: "application/json" }],
      "retry-after": [{ key: "Retry-After", value: "60" }],
      "x-ratelimit-limit": [
        { key: "X-RateLimit-Limit", value: String(limit) },
      ],
      "x-ratelimit-remaining": [
        { key: "X-RateLimit-Remaining", value: "0" },
      ],
    },
    body: JSON.stringify({
      error: "rate_limit_exceeded",
      message: "Too many requests. Try again in 60 seconds.",
      retry_after: 60,
    }),
  };
}

Lo clave: si DynamoDB falla, dejo pasar la request. Nunca bloqueo tráfico legítimo por un fallo de infra. Monitoreo con CloudWatch y ajusto si es necesario.

Fail-open vs fail-closed

Esta es la decisión más importante y más debatida. ¿Qué hacer si el store de rate limits no responde?

Fail-open (lo que uso arriba): en caso de error, permitir la request. Prioriza UX de usuarios legítimos. Riesgo: un atacante podría saturar DynamoDB (cosa poco probable pero posible) para evadir rate limits.

Fail-closed: en caso de error, bloquear la request. Prioriza seguridad. Riesgo: un fallo operacional tumba tu aplicación.

Elegí fail-open para la mayoría de rutas y fail-closed solo para rutas críticas (ej: /api/admin/*). En Lambda@Edge diferencio así:

const criticalPaths = ["/api/admin/", "/api/billing/"];
const isCritical = criticalPaths.some((p) => uri.startsWith(p));

// En caso de error de DynamoDB
if (isCritical) {
  return { status: "503", body: "Service temporarily unavailable" };
}
return request; // fail-open para rutas normales

Response headers informativos

Los clientes serios (apps móviles, integraciones) necesitan saber cuántas requests les quedan. El estándar informal es:

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 245
X-RateLimit-Reset: 1739556660

Los inyecto en el response del origin via viewer-response Lambda@Edge. No los pongo en viewer-request porque ahí solo tengo el contador post-increment.

// lambda-edge/rate-limit-response/index.ts
export const handler = async (event: CloudFrontResponseEvent) => {
  const response = event.Records[0].cf.response;
  const request = event.Records[0].cf.request;

  const remaining = request.headers["x-rate-limit-remaining"]?.[0]?.value;
  if (remaining) {
    response.headers["x-ratelimit-remaining"] = [
      { key: "X-RateLimit-Remaining", value: remaining },
    ];
  }

  return response;
};

Costos reales

Este setup con DynamoDB Global Tables en 4 regiones y Lambda@Edge procesando 50M requests/mes:

Componente	Costo mensual
Lambda@Edge invocations (50M)	$30
Lambda@Edge compute (50M x 20ms x 128MB)	$16
DynamoDB writes (50M x 4 regiones replica)	$125
DynamoDB reads (incluidos en updates)	$0
DynamoDB storage (~5GB promedio)	$5
Total	$176

No es barato. Pero compáralo con el costo de un incidente: el scraping que me levantó a las 3am consumió $400 en Lambda cold starts en 6 horas, más 4 horas de un CTO reactivo, más el churn de usuarios que vieron errores. El rate limit se paga solo la primera vez que para un abuso real.

Para apps más chicas, puedes simplificar. Con 5M requests/mes y 1 región, baja a ~$30/mes.

Patrones avanzados

Whitelisting de IPs conocidas.
Para partners o integraciones legítimas que necesitan alto throughput, mantengo una tabla de IPs whitelisted:

const whitelist = await getWhitelistFromCache();
if (whitelist.has(ip)) {
  return request;
}

Uso un cache in-memory en el Lambda@Edge que se refresca cada 5 minutos desde DynamoDB o un S3 JSON.

Tiered rate limits.
Usuarios en plan Free tienen 100 req/min, Pro tienen 1000, Enterprise tienen 10000. El Lambda@Edge consulta un cache del plan del usuario (que viene en el JWT):

const plan = request.headers["x-user-plan"]?.[0]?.value || "free";
const limit = PLAN_LIMITS[plan] || PLAN_LIMITS.free;

CAPTCHA en lugar de bloqueo.
Para IPs sospechosas (no claramente maliciosas pero sobre el límite), en vez de 429 devuelvo un redirect a una página con CAPTCHA. Si resuelven, emito un token temporal que los whitelistea por 30 minutos.

if (!allowed && count < limit * 2) {
  return {
    status: "302",
    headers: { location: [{ key: "Location", value: "/captcha?redirect=" + uri }] }
  };
}

Lo que aprendí operando esto

1. Las ventanas fijas tienen bordes ruidosos.
Si el límite es 60/min y la ventana resetea en el minuto 0, un cliente que haga 60 requests en el segundo 55 y otras 60 en el segundo 05 del siguiente minuto, hizo 120 en 10 segundos. La ventana fija lo permite. Ventanas deslizantes son más justas pero más caras de calcular. Para la mayoría de casos, las fijas están bien.

2. El contador puede crecer más allá del límite.
Como uso ADD atómico, el contador sigue incrementando aunque ya superó el límite. Eso está OK (solo bloqueas pasado el límite), pero puede confundir si miras DynamoDB directamente y ves valores como count: 847 cuando el límite es 60. Para dashboards, el max value real es menos importante que "cuántos clientes superaron el umbral".

3. Clock skew entre edge locations es mínimo pero existe.
Los edge locations de AWS sincronizan tiempo con NTP pero puede haber diferencias de subsegundo. Para ventanas de 60s no importa, pero si haces ventanas de 1s verás comportamiento extraño.

4. El cold start de Lambda@Edge está mejor pero aún existe.
Mi Lambda de rate limit pesa 2MB con el SDK de DynamoDB pruned. Cold starts son de 180-250ms. Para requests que esperan sub-100ms, eso mata la UX. Solución: Lambda@Edge tiene provisioned concurrency limitada pero real; para rutas críticas, vale la pena configurarla.

5. Observability es esencial.
Sin dashboards, no sabes si tu rate limit funciona. Emito métricas custom a CloudWatch: requests bloqueadas, requests permitidas, por tier, por path. El dashboard me muestra la tasa de bloqueos en tiempo real, y si veo un spike, puedo correlacionar con el tráfico.

6. El rate limit no reemplaza WAF.
Aún tengo WAF delante de CloudFront con reglas básicas: bloqueo de SQL injection, XSS, paths maliciosos, geo-blocking de regiones donde no operamos. WAF se ocupa de "malos conocidos" en protocolo, mi Lambda@Edge se ocupa de "tráfico legítimo pero excesivo". Son capas distintas.

Cuándo NO implementar esto

Si tu app tiene tráfico bajo (menos de 100K requests/día), AWS WAF rate-based rules con la configuración mínima son suficientes y gratis hasta cierto umbral.

Si tu arquitectura no incluye CloudFront, Lambda@Edge no aplica. Tendrías que implementar rate limit en tu API Gateway o en tu backend directamente, con un store central (ElastiCache Redis).

Si tu principal amenaza son ataques DDoS serios (gbps), rate limiting no te salva. Necesitas AWS Shield Advanced con sus mitigaciones especializadas. Rate limiting ayuda contra scraping y abuso de API, no contra attacks volumétricos.

Si no tienes equipo para operar Lambda@Edge (actualizaciones, debugging, monitoring), la complejidad puede ser mayor al beneficio. Empieza con WAF y sube la escalera solo si el beneficio justifica.

El próximo artículo cubre Server Actions de Next.js en Lambda. Formularios sin JavaScript, progressive enhancement, y por qué esto cambia cómo construyo aplicaciones.

i18n en Next.js con DynamoDB, traducciones editables sin redeploy

Gustavo Ramirez — Mon, 02 Feb 2026 14:00:00 +0000

Un cliente internacional me pidió una cosa aparentemente simple: "quiero que marketing pueda cambiar textos sin molestar a desarrollo". Tenían Next.js con i18n en archivos JSON, cada cambio era un PR, un review, un deploy. Total: 2-3 días de friction para cambiar "Comenzar" por "Empezar". Migré todo a DynamoDB con cache en memoria y un panel simple. Marketing edita, se ve en 60 segundos.

Stack final: Next.js 15, DynamoDB con GSI, Lambda para el panel admin, cache en ISR.

Arquitectura

flowchart TB
    M[Marketing<br/>Panel Admin] --> API[Lambda API]
    API --> DDB[(DynamoDB<br/>translations)]
    API --> Inv[Revalidate Tag]
    Inv --> ISR[Next.js ISR]

    User[Usuario final] --> NextApp[Next.js App]
    NextApp -->|getTranslations| Cache{Cache ISR<br/>60s}
    Cache -->|miss| DDB
    Cache -->|hit| User

La clave: las traducciones se guardan en DynamoDB, Next.js las lee con unstable_cache y las sirve cacheadas por 60 segundos. Cuando marketing cambia algo, una llamada a revalidateTag invalida el cache. El usuario final siempre ve algo cacheado, lo que evita que un spike de tráfico destroce DynamoDB.

Modelo de datos

// Primary key: PK = tenant#locale, SK = namespace#key

interface TranslationItem {
  PK: string;        // "acme#es-CO"
  SK: string;        // "common#cta.submit"
  value: string;     // "Enviar"
  updatedAt: number;
  updatedBy: string;
  history: Array<{
    value: string;
    updatedAt: number;
    updatedBy: string;
  }>;
}

// GSI1 para exportar bulk por namespace:
// GSI1PK = tenant#locale#namespace, GSI1SK = key

Tres razones para esta estructura:

Partition key compuesta: tenant#locale permite multi-tenancy con aislamiento perfecto. Acme en español está en una partición, Acme en inglés en otra.
Sort key jerárquica: namespace#key permite queries eficientes por namespace (begins_with(SK, "common#")) sin escanear toda la partición.
History inline: guardo hasta 10 versiones anteriores en el mismo item. Si marketing hace algo mal, rollback en 1 click. Más de 10, al S3.

Capa de acceso

// src/lib/translations/repository.ts
import { DynamoDBClient } from '@aws-sdk/client-dynamodb';
import {
  DynamoDBDocumentClient,
  QueryCommand,
  UpdateCommand,
  GetCommand,
} from '@aws-sdk/lib-dynamodb';

const client = DynamoDBDocumentClient.from(new DynamoDBClient({}));
const TABLE = process.env.TRANSLATIONS_TABLE!;

export async function getTranslationsForNamespace(
  tenant: string,
  locale: string,
  namespace: string
): Promise<Record<string, string>> {
  const result = await client.send(
    new QueryCommand({
      TableName: TABLE,
      KeyConditionExpression: 'PK = :pk AND begins_with(SK, :sk)',
      ExpressionAttributeValues: {
        ':pk': `${tenant}#${locale}`,
        ':sk': `${namespace}#`,
      },
    })
  );

  const translations: Record<string, string> = {};
  for (const item of result.Items || []) {
    const key = (item.SK as string).substring(namespace.length + 1);
    translations[key] = item.value;
  }
  return translations;
}

export async function setTranslation(
  tenant: string,
  locale: string,
  namespace: string,
  key: string,
  value: string,
  updatedBy: string
): Promise<void> {
  const pk = `${tenant}#${locale}`;
  const sk = `${namespace}#${key}`;

  const existing = await client.send(
    new GetCommand({
      TableName: TABLE,
      Key: { PK: pk, SK: sk },
    })
  );

  const now = Date.now();
  const newHistoryEntry = existing.Item
    ? [
        {
          value: existing.Item.value,
          updatedAt: existing.Item.updatedAt,
          updatedBy: existing.Item.updatedBy,
        },
        ...(existing.Item.history || []).slice(0, 9),
      ]
    : [];

  await client.send(
    new UpdateCommand({
      TableName: TABLE,
      Key: { PK: pk, SK: sk },
      UpdateExpression: `
        SET #v = :v,
            updatedAt = :ua,
            updatedBy = :ub,
            history = :h,
            GSI1PK = :gsi1pk,
            GSI1SK = :gsi1sk
      `,
      ExpressionAttributeNames: {
        '#v': 'value',
      },
      ExpressionAttributeValues: {
        ':v': value,
        ':ua': now,
        ':ub': updatedBy,
        ':h': newHistoryEntry,
        ':gsi1pk': `${tenant}#${locale}#${namespace}`,
        ':gsi1sk': key,
      },
    })
  );
}

export async function listAllTranslations(
  tenant: string,
  locale: string
): Promise<Record<string, Record<string, string>>> {
  const namespaces: Record<string, Record<string, string>> = {};

  let lastKey: any = undefined;
  do {
    const result = await client.send(
      new QueryCommand({
        TableName: TABLE,
        KeyConditionExpression: 'PK = :pk',
        ExpressionAttributeValues: { ':pk': `${tenant}#${locale}` },
        ExclusiveStartKey: lastKey,
      })
    );

    for (const item of result.Items || []) {
      const [namespace, ...keyParts] = (item.SK as string).split('#');
      const key = keyParts.join('#');
      if (!namespaces[namespace]) namespaces[namespace] = {};
      namespaces[namespace][key] = item.value;
    }

    lastKey = result.LastEvaluatedKey;
  } while (lastKey);

  return namespaces;
}

Integración con Next.js

// src/lib/translations/server.ts
import { unstable_cache, revalidateTag } from 'next/cache';
import { getTranslationsForNamespace } from './repository';

export const getTranslations = (tenant: string) =>
  unstable_cache(
    async (locale: string, namespace: string) => {
      return getTranslationsForNamespace(tenant, locale, namespace);
    },
    ['translations', tenant],
    {
      revalidate: 60,
      tags: [`translations-${tenant}`],
    }
  );

export function invalidateTranslations(tenant: string) {
  revalidateTag(`translations-${tenant}`);
}

export interface Translator {
  t: (key: string, values?: Record<string, string | number>) => string;
}

export async function createTranslator(
  tenant: string,
  locale: string,
  namespace: string
): Promise<Translator> {
  const dict = await getTranslations(tenant)(locale, namespace);

  return {
    t(key, values) {
      const template = dict[key] ?? key;
      if (!values) return template;
      return Object.entries(values).reduce(
        (acc, [k, v]) => acc.replace(new RegExp(`\\{${k}\\}`, 'g'), String(v)),
        template
      );
    },
  };
}

Uso en Server Components

// src/app/[locale]/products/page.tsx
import { createTranslator } from '@/lib/translations/server';
import { headers } from 'next/headers';

export default async function ProductsPage({
  params,
}: {
  params: Promise<{ locale: string }>;
}) {
  const { locale } = await params;
  const tenant = (await headers()).get('x-tenant-id') || 'default';

  const t = await createTranslator(tenant, locale, 'products');

  return (
    <main>
      <h1>{t.t('page.title')}</h1>
      <p>{t.t('page.description', { count: 42 })}</p>
      <button>{t.t('actions.viewAll')}</button>
    </main>
  );
}

Cuando page.description vale "Mostrando {count} productos", se renderiza "Mostrando 42 productos". Simple, sin librería externa.

Uso en Client Components

Para componentes cliente necesito pasar las traducciones como props o usar un provider:

// src/components/TranslationProvider.tsx
'use client';

import { createContext, useContext, ReactNode } from 'react';

const TranslationContext = createContext<Record<string, string>>({});

export function TranslationProvider({
  translations,
  children,
}: {
  translations: Record<string, string>;
  children: ReactNode;
}) {
  return (
    <TranslationContext.Provider value={translations}>
      {children}
    </TranslationContext.Provider>
  );
}

export function useTranslation() {
  const dict = useContext(TranslationContext);
  return {
    t: (key: string, values?: Record<string, string | number>) => {
      const template = dict[key] ?? key;
      if (!values) return template;
      return Object.entries(values).reduce(
        (acc, [k, v]) => acc.replace(new RegExp(`\\{${k}\\}`, 'g'), String(v)),
        template
      );
    },
  };
}

Y lo hidrato desde el Server Component:

// src/app/[locale]/layout.tsx
import { getTranslations } from '@/lib/translations/server';
import { TranslationProvider } from '@/components/TranslationProvider';

export default async function LocaleLayout({
  children,
  params,
}: {
  children: React.ReactNode;
  params: Promise<{ locale: string }>;
}) {
  const { locale } = await params;
  const tenant = 'default';
  const globalDict = await getTranslations(tenant)(locale, 'global');

  return (
    <html lang={locale}>
      <body>
        <TranslationProvider translations={globalDict}>
          {children}
        </TranslationProvider>
      </body>
    </html>
  );
}

Panel admin para marketing

// src/app/admin/translations/page.tsx
'use client';

import { useState, useEffect } from 'react';

export default function TranslationsAdmin() {
  const [locale, setLocale] = useState('es-CO');
  const [namespace, setNamespace] = useState('common');
  const [items, setItems] = useState<Array<{ key: string; value: string }>>([]);
  const [dirty, setDirty] = useState<Record<string, string>>({});

  useEffect(() => {
    fetch(`/api/translations?locale=${locale}&namespace=${namespace}`)
      .then((r) => r.json())
      .then((data) => {
        setItems(
          Object.entries(data).map(([key, value]) => ({
            key,
            value: value as string,
          }))
        );
      });
  }, [locale, namespace]);

  async function saveChanges() {
    await fetch('/api/translations/batch', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        locale,
        namespace,
        changes: dirty,
      }),
    });
    setDirty({});
    alert('Guardado. Los cambios aparecen en producción en 60 segundos.');
  }

  return (
    <div className="p-6">
      <div className="flex gap-4 mb-6">
        <select
          value={locale}
          onChange={(e) => setLocale(e.target.value)}
          className="border rounded px-3 py-2"
        >
          <option value="es-CO">Español (Colombia)</option>
          <option value="es-MX">Español (México)</option>
          <option value="en-US">English (US)</option>
          <option value="pt-BR">Português (Brasil)</option>
        </select>

        <select
          value={namespace}
          onChange={(e) => setNamespace(e.target.value)}
          className="border rounded px-3 py-2"
        >
          <option value="common">Common</option>
          <option value="products">Products</option>
          <option value="checkout">Checkout</option>
          <option value="emails">Emails</option>
        </select>

        <button
          onClick={saveChanges}
          disabled={Object.keys(dirty).length === 0}
          className="bg-blue-600 text-white px-4 py-2 rounded disabled:opacity-50"
        >
          Guardar {Object.keys(dirty).length} cambios
        </button>
      </div>

      <table className="w-full border-collapse">
        <thead>
          <tr className="border-b">
            <th className="text-left py-2 w-1/3">Key</th>
            <th className="text-left py-2">Valor</th>
          </tr>
        </thead>
        <tbody>
          {items.map(({ key, value }) => (
            <tr key={key} className="border-b hover:bg-gray-50">
              <td className="py-2 font-mono text-sm text-gray-600">{key}</td>
              <td className="py-2">
                <input
                  type="text"
                  defaultValue={value}
                  onChange={(e) => {
                    setDirty({ ...dirty, [key]: e.target.value });
                  }}
                  className="w-full border rounded px-2 py-1"
                />
              </td>
            </tr>
          ))}
        </tbody>
      </table>
    </div>
  );
}

API con invalidación

// src/app/api/translations/batch/route.ts
import { NextRequest, NextResponse } from 'next/server';
import { setTranslation } from '@/lib/translations/repository';
import { invalidateTranslations } from '@/lib/translations/server';
import { getServerSession } from 'next-auth';

export async function POST(req: NextRequest) {
  const session = await getServerSession();
  if (!session?.user?.email) {
    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
  }

  const { locale, namespace, changes } = await req.json();
  const tenant = 'default';

  for (const [key, value] of Object.entries(changes)) {
    await setTranslation(tenant, locale, namespace, key, value as string, session.user.email);
  }

  invalidateTranslations(tenant);

  return NextResponse.json({ updated: Object.keys(changes).length });
}

Comparativa con alternativas

Aspecto	JSON files	i18next + API	Crowdin	Mi approach
Edit sin redeploy	No	Sí	Sí	Sí
Costo mensual	0	0	Desde 40 USD	1-5 USD
Latencia edit → prod	30 min	5 min	10 min	60 segundos
Historial de cambios	git	Custom	Sí	Sí (inline)
Multi-tenant aislado	Por folder	Custom	Enterprise	Nativo
Traducción asistida	No	No	Sí	No

Crowdin gana en features (memoria de traducción, assistencia IA). Yo gano en costo, control y velocidad para un caso simple.

Lo que aprendí

1. On-demand revalidation es crítico.
Sin revalidateTag, el TTL de 60s dicta la latencia. Con revalidación explícita, el cambio se propaga al primer request después de la llamada a revalidateTag. Combinado con edge CDN, el cambio llega globalmente en 10-15 segundos.

2. DynamoDB Query es rápido pero tiene latencia.
Cada Query tarda 10-30ms. Para 10 namespaces en la misma página, son 300ms acumulados sin cache. El unstable_cache de Next me salva: después del primer usuario, el resto paga 1-2ms de cache hit.

3. JSON files como fallback.
Exporto un snapshot semanal de DynamoDB a JSON files en public/fallback-translations/. Si DynamoDB está caído y Next.js no puede leer, cargo los JSON. La app sigue funcionando con traducciones "stale" pero visibles.

4. Pluralization es tema aparte.
Mi función t() simple no maneja "1 producto" vs "2 productos". Para eso agregué reglas CLDR:

function plural(count: number, singular: string, plural: string) {
  return count === 1 ? singular : plural;
}
t.t('products.count', { count: 5, label: plural(5, 'producto', 'productos') });

Feo pero funciona. Para idiomas con plurales complejos (ruso, árabe) usé Intl.PluralRules.

5. Los keys en código son más fáciles que los valores default.
Algunos frameworks (i18next) usan el texto inglés como key. t('Welcome back, {name}'). Yo uso keys abstractos: t('home.greeting'). Ventaja: cambiar "Welcome back" a "Hi there" es cambiar el valor, no refactorizar 200 archivos. Desventaja: los keys no se autoexplican leyendo el código. Trade-off que acepto.

Cuándo NO usar esto

Si tu app tiene pocos textos y no cambian, JSON files en git son más simples. No metas DynamoDB por el gusto.

Si tu equipo de traducción es grande y necesita memoria de traducción o TM, Crowdin/Lokalise tienen features que no vale reinventar.

Si sirves idiomas RTL (árabe, hebreo), asegúrate que tu layout soporta dir="rtl". Los textos son solo parte de la i18n. Mi sistema no resuelve esto.

El próximo artículo cubre rate limiting en edge con CloudFront y DynamoDB. Cómo defender tu app de bots abusivos sin agregar latencia a usuarios reales.

Bundle splitting guiado por métricas reales de CloudWatch RUM

Gustavo Ramirez — Wed, 21 Jan 2026 14:00:00 +0000

Bundle splitting es fácil. Lo difícil es saber qué splitear y qué no. Muchos equipos splitean basándose en intuición y terminan con más overhead que ganancia: 200 chunks chicos que tardan más que 3 medianos por el costo del HTTP overhead. Durante una migración de un portal bancario descubrí una estrategia mejor: dejar que CloudWatch RUM me diga qué rutas realmente importan y splitear por ahí.

Por qué intuición no basta

El patrón típico es dividir por ruta:

const Dashboard = lazy(() => import('./pages/Dashboard'));
const Reports = lazy(() => import('./pages/Reports'));
const Settings = lazy(() => import('./pages/Settings'));

Parece razonable. Pero si el 95% de los usuarios solo ven Dashboard y Reports en la misma sesión, estás pagando el costo de dos chunks cuando uno solo habría sido mejor. Por otro lado, Settings lo ven 5 usuarios al mes. Descargarlo por defecto es desperdicio.

Necesitaba datos reales sobre qué rutas visitan los usuarios, en qué orden y con qué frecuencia. CloudWatch RUM los tiene.

Instrumentación personalizada de RUM

RUM captura page views automáticamente. Pero yo necesitaba medir también qué chunks se cargaban en cada visita:

// src/lib/rum.ts
import { AwsRum, AwsRumConfig } from 'aws-rum-web';

const config: AwsRumConfig = {
  sessionSampleRate: 1,
  guestRoleArn: process.env.VITE_RUM_GUEST_ROLE_ARN!,
  identityPoolId: process.env.VITE_RUM_IDENTITY_POOL!,
  endpoint: 'https://dataplane.rum.us-east-1.amazonaws.com',
  telemetries: ['performance', 'errors', 'http'],
  allowCookies: true,
  enableXRay: false,
};

export const rum = new AwsRum(
  process.env.VITE_RUM_APP_MONITOR_ID!,
  '1.0.0',
  'us-east-1',
  config
);

const originalImport = (window as any).__dynamicImport;
(window as any).__dynamicImport = async (chunkName: string, importFn: () => Promise<any>) => {
  const start = performance.now();
  try {
    const module = await importFn();
    const duration = performance.now() - start;

    rum.recordEvent('chunk_loaded', {
      chunkName,
      duration,
      route: window.location.pathname,
    });

    return module;
  } catch (err) {
    rum.recordEvent('chunk_error', {
      chunkName,
      error: String(err),
      route: window.location.pathname,
    });
    throw err;
  }
};

Después uso este wrapper en los lazy:

// src/routes.tsx
import { lazy } from 'react';

const wrap = (name: string, fn: () => Promise<any>) => lazy(() => {
  return (window as any).__dynamicImport(name, fn);
});

export const Dashboard = wrap('dashboard', () => import('./pages/Dashboard'));
export const Reports = wrap('reports', () => import('./pages/Reports'));
export const Settings = wrap('settings', () => import('./pages/Settings'));
export const UserProfile = wrap('user-profile', () => import('./pages/UserProfile'));
export const AdminPanel = wrap('admin', () => import('./pages/AdminPanel'));

Exportando eventos a CloudWatch Logs Insights

CloudWatch RUM pone eventos custom en CloudWatch Logs automáticamente (en un log group específico del app monitor). Desde ahí puedo correr Logs Insights:

fields @timestamp, event_details.chunkName as chunk, event_details.route as route
| filter event_type = "chunk_loaded"
| stats count(*) as loads by chunk
| sort loads desc

Salida real de un mes de mi aplicación:

chunk           | loads
----------------|--------
dashboard       | 48210
reports         | 32104
user-profile    | 8421
settings        | 1203
admin           | 145
integrations    | 89
help-center     | 42
onboarding      | 12

Dashboard y Reports son el 86% del tráfico. Juntarlos en un solo chunk tendría sentido si sus dependencias se superponen mucho.

Luego correlaciono esto con el tamaño de cada chunk:

// scripts/analyze-bundles.ts
import fs from 'node:fs';
import path from 'node:path';

interface Stats {
  assets: Array<{
    name: string;
    size: number;
    chunks: string[];
  }>;
  chunks: Array<{
    id: string;
    names: string[];
    files: string[];
  }>;
}

const stats: Stats = JSON.parse(
  fs.readFileSync(path.join('dist', 'stats.json'), 'utf-8')
);

const chunkSizes = new Map<string, number>();
for (const chunk of stats.chunks) {
  const name = chunk.names[0] || chunk.id;
  const totalSize = chunk.files
    .map((f) => stats.assets.find((a) => a.name === f)?.size ?? 0)
    .reduce((a, b) => a + b, 0);
  chunkSizes.set(name, totalSize);
}

const rumCounts = new Map<string, number>([
  ['dashboard', 48210],
  ['reports', 32104],
  ['user-profile', 8421],
  ['settings', 1203],
  ['admin', 145],
  ['integrations', 89],
  ['help-center', 42],
  ['onboarding', 12],
]);

console.log('chunk\tsize_kb\tloads/month\ttotal_mb_transferred');
for (const [name, size] of chunkSizes) {
  const loads = rumCounts.get(name) ?? 0;
  const totalMb = (size * loads) / (1024 * 1024);
  console.log(
    `${name}\t${(size / 1024).toFixed(1)}\t${loads}\t${totalMb.toFixed(1)}`
  );
}

Resultado:

chunk           size_kb   loads     transferred_mb
dashboard       340       48210     16030
reports         220       32104     6910
user-profile    85        8421      705
settings        45        1203      53
admin           180       145       26
integrations    95        89        8
help-center     30        42        1
onboarding      250       12        3

Descubrimientos accionables:

Onboarding pesa 250KB y se descarga 12 veces al mes. Total transferido: 3MB. Pero esos 12 usuarios nuevos están bajando una página pesada. Optimización: dividir onboarding en pasos lazy.
Admin pesa 180KB para 145 usuarios/mes. Ese chunk probablemente está en webpack chunks vendor con mucho código compartido. No tocar.
Dashboard + Reports juntos suman ~22GB transferidos al mes. Si sus dependencias se solapan, combinarlos ahorraría tráfico real.

Analizando overlap de dependencias

npx webpack-bundle-analyzer dist/stats.json

Visualmente se ven los treemaps. Mejor aún, automatizo:

// scripts/chunk-overlap.ts
import fs from 'node:fs';

interface Stats {
  modules: Array<{
    name: string;
    size: number;
    chunks: string[];
  }>;
}

const stats: Stats = JSON.parse(fs.readFileSync('dist/stats.json', 'utf-8'));

function overlap(chunkA: string, chunkB: string) {
  const modsA = new Set<string>();
  const modsB = new Set<string>();
  let sharedSize = 0;

  for (const mod of stats.modules) {
    if (mod.chunks.includes(chunkA)) modsA.add(mod.name);
    if (mod.chunks.includes(chunkB)) modsB.add(mod.name);
  }

  for (const mod of stats.modules) {
    if (mod.chunks.includes(chunkA) && mod.chunks.includes(chunkB)) {
      sharedSize += mod.size;
    }
  }

  return {
    sharedModules: [...modsA].filter((m) => modsB.has(m)).length,
    sharedSize,
  };
}

console.log('Dashboard + Reports:', overlap('dashboard', 'reports'));
console.log('Dashboard + Settings:', overlap('dashboard', 'settings'));

Salida:

Dashboard + Reports: { sharedModules: 42, sharedSize: 85340 }
Dashboard + Settings: { sharedModules: 8, sharedSize: 4120 }

Dashboard y Reports comparten 85KB. Si los uniera en un solo chunk de 475KB (340 + 220 - 85), muchos usuarios se ahorrarían una segunda request. Para los que solo ven Dashboard, pagan 135KB extra. Decisión de negocio: ¿cuántos ven solo Dashboard y nunca Reports?

Vuelvo a Logs Insights:

fields @timestamp, event_details.route as route, session_id
| filter event_type = "chunk_loaded"
| stats
    count_distinct(session_id) as sessions,
    count(distinct event_details.chunkName) as chunks_used
  by session_id

El 78% de sesiones carga tanto Dashboard como Reports. Combinar los chunks sería correcto.

La optimización con Webpack

// webpack.config.js (fragmento)
module.exports = {
  optimization: {
    splitChunks: {
      chunks: 'all',
      cacheGroups: {
        coreFlow: {
          name: 'core-flow',
          test: /[\\/]src[\\/]pages[\\/](Dashboard|Reports)[\\/]/,
          priority: 20,
          minChunks: 1,
        },
        adminBundle: {
          name: 'admin-bundle',
          test: /[\\/]src[\\/]pages[\\/](AdminPanel|Integrations)[\\/]/,
          priority: 15,
          minChunks: 1,
        },
        vendor: {
          name: 'vendor',
          test: /[\\/]node_modules[\\/]/,
          priority: 10,
          reuseExistingChunk: true,
        },
      },
    },
  },
};

En Vite el approach es parecido:

// vite.config.ts
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';

export default defineConfig({
  plugins: [react()],
  build: {
    rollupOptions: {
      output: {
        manualChunks: (id) => {
          if (id.includes('/pages/Dashboard') || id.includes('/pages/Reports')) {
            return 'core-flow';
          }
          if (id.includes('/pages/AdminPanel') || id.includes('/pages/Integrations')) {
            return 'admin-bundle';
          }
          if (id.includes('node_modules')) {
            return 'vendor';
          }
        },
      },
    },
  },
});

Prefetch basado en patrones RUM

Otro insight de los datos: después de Dashboard, el 60% de usuarios va a Reports en menos de 90 segundos. Entonces prefetcheo Reports en idle time:

// src/hooks/useRoutePrefetch.ts
import { useEffect } from 'react';
import { useLocation } from 'react-router-dom';

const PREFETCH_RULES: Record<string, string[]> = {
  '/dashboard': ['/reports'],
  '/reports': ['/reports/detail'],
  '/user-profile': ['/settings'],
};

const prefetchChunk = (route: string) => {
  switch (route) {
    case '/reports':
      return import('./pages/Reports');
    case '/reports/detail':
      return import('./pages/ReportsDetail');
    case '/settings':
      return import('./pages/Settings');
    default:
      return null;
  }
};

export function useRoutePrefetch() {
  const location = useLocation();

  useEffect(() => {
    const candidates = PREFETCH_RULES[location.pathname];
    if (!candidates) return;

    if ('requestIdleCallback' in window) {
      const id = requestIdleCallback(() => {
        for (const route of candidates) {
          prefetchChunk(route);
        }
      });
      return () => cancelIdleCallback(id);
    } else {
      const timeout = setTimeout(() => {
        for (const route of candidates) {
          prefetchChunk(route);
        }
      }, 2000);
      return () => clearTimeout(timeout);
    }
  }, [location.pathname]);
}

Resultado: cuando el usuario navega a Reports, el chunk ya está en memoria. Transición instantánea sin spinner.

Benchmark de la optimización

Antes:

Initial load:
  main.js         180 KB
  vendor.js       420 KB
  Total first paint: 600 KB

Navigation Dashboard -> Reports:
  dashboard.js    340 KB (cached)
  reports.js      220 KB (new download)
  Spinner visible: ~400ms

Después:

Initial load:
  main.js         180 KB
  vendor.js       385 KB (admin splits moved)
  Total first paint: 565 KB

Navigation Dashboard -> Reports:
  core-flow.js    475 KB (cached, incluye ambos)
  Spinner visible: 0ms

Mejora:

Métrica	Antes	Después	Cambio
First Contentful Paint	1.8s	1.7s	-5%
Time to Interactive	3.2s	2.9s	-9%
Route transition (D→R)	400ms	0ms	-100%
Bytes totales/sesión media	1.2 MB	850 KB	-30%

El -30% en bytes totales viene de que muchos usuarios ya no descargan admin, onboarding y settings por defecto.

Lo que aprendí

1. CloudWatch RUM tiene tier gratuito generoso.
Los primeros 100K eventos al mes son gratis. Para una app con 50K sesiones al mes, cabía sin costo. Pasado ese umbral, 1 USD por 100K eventos.

2. Sampling rate 100% no siempre es correcto.
Usé sessionSampleRate: 1 al inicio. Para 200K sesiones/mes, generaba 10M eventos. Me pasé al tier pago. Bajé a 0.1 (10%) para el día a día y subo a 1 cuando debug performance issues puntuales.

3. Los eventos custom tienen schema rígido.
RUM guarda eventos custom en event_details como JSON pero con límite de campos y tipos. Probé pasar arrays, objetos anidados: se truncaban. Keep it flat: strings y números simples.

4. Vite no emite stats.json por defecto.
Necesitaba stats para análisis. Plugin: rollup-plugin-visualizer con emitFile: true, filename: 'stats.json', template: 'raw-data'. Diferente al webpack-bundle-analyzer pero parseable.

5. Prefetch agresivo consume datos móviles.
Usuarios de planes limitados se quejaron del uso de datos. Agregué check: navigator.connection?.saveData === true desactiva prefetch, y si el effectiveType es '2g' o 'slow-2g' tampoco prefetcheo.

Cuándo NO splitear

Si tu bundle total es menor a 200KB, no splitees. El overhead HTTP de chunks pequeños te cuesta más que el beneficio.

Si tus usuarios son internos y siempre están en red corporativa con latencia baja, el beneficio es marginal. Carga toda la app y dejá que el cache del browser haga el resto.

Si no tenés métricas reales de uso, no improvises. Splitear basándose en "parece que esta ruta es rara" termina en decisiones equivocadas. Instrumentá primero.

El próximo artículo cubre internacionalización con Next.js y DynamoDB para traducciones editables por equipo no técnico. Spoiler: reemplazamos Crowdin con 100 líneas de código.

Playwright en AWS CodeBuild con contenedores custom para E2E serios

Gustavo Ramirez — Fri, 09 Jan 2026 14:00:00 +0000

Correr Playwright en CodeBuild suena simple: instalas Playwright en el buildspec, ejecutas tests, reportas. Pero cuando tu suite crece a 300+ tests E2E, la cosa cambia. Los cold starts de instalar browsers cada build consumen minutos preciosos. Las imágenes default de CodeBuild tienen versiones que no siempre sincronizan con tu versión local. Y el paralelismo real requiere orquestación.

Este artículo es la configuración completa que llevo usando un año. Un contenedor Docker custom con Playwright preinstalado, CodeBuild ejecutando con paralelismo batch, y artefactos que sirven para debuggear fallos sin adivinar. La suite de 300 tests corre en 8 minutos en vez de los 40 que tomaba antes.

El problema con la imagen default de CodeBuild

La imagen aws/codebuild/standard:7.0 tiene Node pero no Playwright. Cada build hace:

# buildspec.yml (forma ingenua)
phases:
  install:
    runtime-versions:
      nodejs: 20
    commands:
      - npm ci
      - npx playwright install --with-deps chromium firefox webkit
  build:
    commands:
      - npx playwright test

El npx playwright install --with-deps baja Chromium (170MB), Firefox (90MB), WebKit (80MB), más dependencias del sistema. En mi proyecto eso tomaba 3-5 minutos cada build. Con 30 builds al día, son ~2 horas diarias de CPU gastadas reinstalando browsers que no cambiaron.

La solución obvia: imagen Docker custom con todo preinstalado.

La imagen custom

# docker/playwright-codebuild/Dockerfile
FROM mcr.microsoft.com/playwright:v1.49.0-jammy

USER root

# Herramientas que CodeBuild espera
RUN apt-get update && apt-get install -y \
    git \
    curl \
    jq \
    unzip \
    ca-certificates \
    && rm -rf /var/lib/apt/lists/*

# AWS CLI v2
RUN curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o "awscliv2.zip" \
    && unzip awscliv2.zip \
    && ./aws/install \
    && rm -rf awscliv2.zip aws/

# Node cache config para builds más rápidos
ENV NPM_CONFIG_CACHE=/tmp/.npm
ENV PLAYWRIGHT_BROWSERS_PATH=/ms-playwright

WORKDIR /workspace

# Verificación que los browsers están listos
RUN npx playwright --version && \
    ls -la /ms-playwright

La clave: uso la imagen oficial de Microsoft (mcr.microsoft.com/playwright) con los browsers preinstalados en /ms-playwright. Agrego AWS CLI, git, y herramientas que CodeBuild usa internamente.

Pushear a ECR

# scripts/push-image.sh
#!/bin/bash
set -e

REGION=${AWS_REGION:-us-east-1}
ACCOUNT_ID=$(aws sts get-caller-identity --query Account --output text)
REPO_NAME=playwright-codebuild
TAG=${1:-v1.49.0}

# Crear repo si no existe
aws ecr describe-repositories --repository-names $REPO_NAME --region $REGION \
    || aws ecr create-repository --repository-name $REPO_NAME --region $REGION

# Login
aws ecr get-login-password --region $REGION \
    | docker login --username AWS --password-stdin \
    $ACCOUNT_ID.dkr.ecr.$REGION.amazonaws.com

# Build y push
docker build -t $REPO_NAME:$TAG ./docker/playwright-codebuild/
docker tag $REPO_NAME:$TAG \
    $ACCOUNT_ID.dkr.ecr.$REGION.amazonaws.com/$REPO_NAME:$TAG
docker push $ACCOUNT_ID.dkr.ecr.$REGION.amazonaws.com/$REPO_NAME:$TAG

echo "Image pushed: $ACCOUNT_ID.dkr.ecr.$REGION.amazonaws.com/$REPO_NAME:$TAG"

Corro este script cada vez que actualizo Playwright. El resto del tiempo, CodeBuild usa la imagen cacheada.

El CDK para el proyecto CodeBuild

// cdk/lib/e2e-pipeline-stack.ts
import { Stack, StackProps, Duration } from "aws-cdk-lib";
import {
  Project,
  Source,
  BuildEnvironment,
  LinuxBuildImage,
  ComputeType,
  BuildSpec,
  Cache,
  LocalCacheMode,
} from "aws-cdk-lib/aws-codebuild";
import { Bucket } from "aws-cdk-lib/aws-s3";
import { Repository } from "aws-cdk-lib/aws-ecr";
import { PolicyStatement } from "aws-cdk-lib/aws-iam";
import { Construct } from "constructs";

export class E2EPipelineStack extends Stack {
  constructor(scope: Construct, id: string, props?: StackProps) {
    super(scope, id, props);

    const artifactsBucket = new Bucket(this, "E2EArtifacts", {
      lifecycleRules: [{ expiration: Duration.days(30) }],
    });

    const ecrRepo = Repository.fromRepositoryName(
      this,
      "PlaywrightImage",
      "playwright-codebuild"
    );

    const project = new Project(this, "E2EProject", {
      projectName: "e2e-tests",
      source: Source.gitHub({
        owner: "mi-org",
        repo: "mi-app",
        webhook: true,
        webhookFilters: [],
      }),
      environment: {
        buildImage: LinuxBuildImage.fromEcrRepository(ecrRepo, "v1.49.0"),
        computeType: ComputeType.LARGE,
        privileged: false,
      },
      cache: Cache.local(LocalCacheMode.CUSTOM, LocalCacheMode.SOURCE),
      buildSpec: BuildSpec.fromSourceFilename("buildspec-e2e.yml"),
      timeout: Duration.minutes(30),
      concurrentBuildLimit: 5,
    });

    // Permisos para subir artefactos
    artifactsBucket.grantReadWrite(project);

    // Permisos para leer secrets de los tests (URLs, credenciales de test user)
    project.addToRolePolicy(
      new PolicyStatement({
        actions: ["secretsmanager:GetSecretValue"],
        resources: [
          `arn:aws:secretsmanager:${this.region}:${this.account}:secret:e2e/*`,
        ],
      })
    );
  }
}

Tres cosas importantes en esta configuración. ComputeType.LARGE da 8 vCPUs y 15GB RAM, suficiente para correr 4-6 workers de Playwright en paralelo. concurrentBuildLimit: 5 evita que 10 PRs al mismo tiempo saturen tu cuenta. Y Cache.local con CUSTOM permite cachear node_modules entre builds del mismo branch.

El buildspec completo

# buildspec-e2e.yml
version: 0.2

env:
  variables:
    PLAYWRIGHT_BROWSERS_PATH: /ms-playwright
  secrets-manager:
    TEST_USER_EMAIL: e2e/test-users:email
    TEST_USER_PASSWORD: e2e/test-users:password

phases:
  install:
    commands:
      - echo "Playwright version check:"
      - npx playwright --version

      - echo "Installing project dependencies..."
      - npm ci --prefer-offline --no-audit

  pre_build:
    commands:
      - echo "Shard $SHARD_INDEX of $SHARD_TOTAL"
      - mkdir -p test-results/shard-$SHARD_INDEX

  build:
    commands:
      - echo "Running tests for shard $SHARD_INDEX/$SHARD_TOTAL"
      - |
        BASE_URL=$E2E_BASE_URL \
        CI=true \
        npx playwright test \
          --shard=$SHARD_INDEX/$SHARD_TOTAL \
          --reporter=list,html,json \
          --output=test-results/shard-$SHARD_INDEX \
          || echo "Tests failed, collecting artifacts"

  post_build:
    commands:
      - echo "Collecting artifacts..."
      - ls -la test-results/shard-$SHARD_INDEX

      - |
        if [ -d "playwright-report" ]; then
          aws s3 sync playwright-report \
            s3://$ARTIFACTS_BUCKET/$CODEBUILD_BUILD_ID/shard-$SHARD_INDEX/ \
            --quiet
          echo "Report: https://$ARTIFACTS_BUCKET.s3.amazonaws.com/$CODEBUILD_BUILD_ID/shard-$SHARD_INDEX/index.html"
        fi

      - |
        if [ -d "test-results/shard-$SHARD_INDEX" ]; then
          aws s3 sync test-results/shard-$SHARD_INDEX \
            s3://$ARTIFACTS_BUCKET/$CODEBUILD_BUILD_ID/shard-$SHARD_INDEX-traces/ \
            --quiet
        fi

artifacts:
  files:
    - 'test-results/**/*'
    - 'playwright-report/**/*'
  base-directory: .

cache:
  paths:
    - 'node_modules/**/*'
    - '/tmp/.npm/**/*'

Tres detalles importantes.

Primero, uso secrets-manager de CodeBuild para inyectar credenciales de test. Los secrets van a variables de entorno sin que queden expuestos en logs.

Segundo, --shard=$SHARD_INDEX/$SHARD_TOTAL es nativo de Playwright. Si le paso --shard=2/4, solo corre un cuarto de los tests (los que le tocan al shard 2). Combinando esto con múltiples CodeBuild en paralelo, reparto la suite automáticamente.

Tercero, subo artefactos a S3 en post_build. El reporte HTML de Playwright queda accesible via URL pública, con traces (screenshots, videos, action logs) para cada fallo.

Orquestación con batch builds

CodeBuild soporta "batch builds" que lanzan múltiples builds en paralelo con config distinta. Esto es la clave para paralelismo real.

# buildspec-e2e-batch.yml
version: 0.2

batch:
  fast-fail: false
  build-list:
    - identifier: shard_1
      env:
        variables:
          SHARD_INDEX: "1"
          SHARD_TOTAL: "4"
    - identifier: shard_2
      env:
        variables:
          SHARD_INDEX: "2"
          SHARD_TOTAL: "4"
    - identifier: shard_3
      env:
        variables:
          SHARD_INDEX: "3"
          SHARD_TOTAL: "4"
    - identifier: shard_4
      env:
        variables:
          SHARD_INDEX: "4"
          SHARD_TOTAL: "4"

# Cada build corre el buildspec-e2e.yml con su SHARD_INDEX

Al trigger del webhook, CodeBuild lanza 4 builds en paralelo, cada uno corriendo 1/4 de la suite. Si cada shard toma 8 minutos, la suite total termina en 8 minutos (no 32).

Para habilitar batch builds en CDK:

// dentro del Project
batchBuildConfig: {
  serviceRole: project.role!,
  combineArtifacts: true,
  restrictions: {
    maximumBuildsAllowed: 5,
    computeTypesAllowed: [ComputeType.LARGE, ComputeType.MEDIUM],
  },
},

Playwright config para shards

// playwright.config.ts
import { defineConfig, devices } from "@playwright/test";

export default defineConfig({
  testDir: "./e2e",
  fullyParallel: true,
  forbidOnly: !!process.env.CI,
  retries: process.env.CI ? 2 : 0,
  workers: process.env.CI ? 4 : undefined,
  reporter: [
    ["list"],
    ["html", { open: "never" }],
    ["json", { outputFile: "test-results/results.json" }],
  ],
  use: {
    baseURL: process.env.E2E_BASE_URL,
    trace: "retain-on-failure",
    screenshot: "only-on-failure",
    video: "retain-on-failure",
    viewport: { width: 1280, height: 720 },
  },
  projects: [
    {
      name: "chromium",
      use: { ...devices["Desktop Chrome"] },
    },
    {
      name: "firefox",
      use: { ...devices["Desktop Firefox"] },
    },
    {
      name: "webkit",
      use: { ...devices["Desktop Safari"] },
    },
  ],
  outputDir: "test-results",
});

trace: "retain-on-failure" guarda el trace solo cuando un test falla. El trace incluye screenshots de cada acción, network logs, y timeline. Puedes reproducir exactamente qué pasó descargando el .zip y abriéndolo con npx playwright show-trace trace.zip.

Merge de reportes

Con 4 shards generando reportes separados, quiero un reporte consolidado al final. Para eso agrego un build final que corre después de los shards:

# buildspec-e2e-merge.yml
version: 0.2

batch:
  build-list:
    - identifier: shard_1
      # ... como antes
    - identifier: shard_2
      # ...
    - identifier: shard_3
      # ...
    - identifier: shard_4
      # ...
    - identifier: merge_reports
      depend-on:
        - shard_1
        - shard_2
        - shard_3
        - shard_4
      buildspec: buildspec-merge.yml
      env:
        compute-type: BUILD_GENERAL1_SMALL

El buildspec-merge descarga todos los reportes de S3 y los mergea:

# buildspec-merge.yml
version: 0.2

phases:
  install:
    commands:
      - npm install -g playwright-merge-html-reports

  build:
    commands:
      - mkdir -p merged-report
      - aws s3 sync s3://$ARTIFACTS_BUCKET/$CODEBUILD_INITIATOR/ ./all-shards/
      - playwright-merge-html-reports all-shards/ -o merged-report/
      - aws s3 sync merged-report/ \
          s3://$ARTIFACTS_BUCKET/$CODEBUILD_INITIATOR/merged/ --quiet
      - echo "Merged report: https://$ARTIFACTS_BUCKET.s3.amazonaws.com/$CODEBUILD_INITIATOR/merged/index.html"

Notificaciones a Slack al fallar

El buildspec también dispara notificaciones cuando hay fallos. Uso EventBridge + SNS + un Lambda de formateo:

// cdk/lib/notifications-stack.ts
import { Rule } from "aws-cdk-lib/aws-events";
import { LambdaFunction } from "aws-cdk-lib/aws-events-targets";
import { NodejsFunction } from "aws-cdk-lib/aws-lambda-nodejs";

const notifyFn = new NodejsFunction(this, "NotifyFailure", {
  entry: "lambdas/notify-failure.ts",
  environment: {
    SLACK_WEBHOOK_URL: process.env.SLACK_WEBHOOK!,
  },
});

new Rule(this, "E2EFailureRule", {
  eventPattern: {
    source: ["aws.codebuild"],
    detailType: ["CodeBuild Build State Change"],
    detail: {
      "project-name": ["e2e-tests"],
      "build-status": ["FAILED"],
    },
  },
  targets: [new LambdaFunction(notifyFn)],
});

El Lambda formatea el evento y postea en Slack con link al reporte:

// lambdas/notify-failure.ts
export const handler = async (event: any) => {
  const { "build-id": buildId, "project-name": project } = event.detail;
  const shortId = buildId.split("/").pop()?.split(":").pop();
  const reportUrl = `https://${process.env.BUCKET}.s3.amazonaws.com/${buildId}/merged/index.html`;

  await fetch(process.env.SLACK_WEBHOOK_URL!, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      blocks: [
        {
          type: "section",
          text: {
            type: "mrkdwn",
            text: `:x: E2E tests failed on *${project}*\nBuild: \`${shortId}\`\n<${reportUrl}|Ver reporte completo>`,
          },
        },
      ],
    }),
  });
};

Números reales del setup

Proyecto con 340 tests Playwright en Chromium + Firefox + WebKit. Antes del setup custom:

Fase	Tiempo antes	Tiempo después
Install Playwright browsers	3.5 min	0 (preinstalados)
`npm ci`	2 min	25s (con cache local)
Run tests serial	34 min	-
Run tests shard 1/4 paralelo	-	8 min
Total wall-clock	39.5 min	8.5 min

Reducción de 80% en tiempo, con la suite completa corriendo en cada PR.

Lo que aprendí afinando esto

1. Las imágenes de Microsoft se actualizan cada release de Playwright.
Un día actualicé Playwright en el proyecto y los tests empezaron a fallar en CI pero no localmente. La imagen de CodeBuild usaba Playwright 1.45 pero el package.json ya estaba en 1.47. Cree un pre-commit que valida que los dos matchean, o el build falla rápido con mensaje claro.

2. El cache local de CodeBuild es frágil.
Cache.local(LocalCacheMode.CUSTOM) funciona pero no siempre. Si el build corre en una instancia nueva del pool de CodeBuild, el cache está vacío. Para garantías, usa S3 cache, aunque es más lento. Para pragmatismo, acepto que a veces el cache no está y tomo el hit.

3. Los secrets del Secrets Manager suben el costo de builds.
Cada build con secrets mana hace API calls. Para 30 builds/día con 5 secrets cada uno, son 4,500 calls/mes extras. Si tienes muchos secrets, usa Parameter Store (gratis hasta cierto límite) o inyecta vía variables de entorno del proyecto CodeBuild para secretos no críticos.

4. El timeout de CodeBuild cuenta el pull de imagen.
Si tu imagen pesa 2GB, el primer pull en una instancia nueva toma 2-3 minutos que cuentan contra tu timeout de 30 minutos. Tuve builds que timeouteaban no porque los tests tardaran, sino porque la imagen tardó mucho. Solución: mantener la imagen chica (la mía pesa 1.1GB) y habilitar image pull cache en la config del proyecto.

5. fail-fast apagado cambia la estrategia de debugging.
Con fast-fail: false en batch builds, todos los shards terminan aunque uno falle. Esto te da visibilidad completa del estado de la suite, pero también significa que tardas más en detectar "está roto". Para main branch uso fail-fast: true (rápido), para PRs fail-fast: false (completo).

6. Videos y traces ocupan espacio.
340 tests con video en fallos generan gigas cuando hay mala semana. Configuré lifecycle en el bucket de artefactos para borrar a los 30 días. También limito video: "retain-on-failure" en vez de on para grabar solo cuando hay algo que mirar.

Cuándo NO usar este setup

Si tu suite tiene menos de 20 tests, la infra es sobrecosto. Ejecutar en GitHub Actions con el action oficial de Playwright es más simple.

Si tu equipo no tiene experiencia con Docker y CI, mantener imágenes custom agrega fricción. Acepta imágenes default de CodeBuild con un poco más de tiempo de build al principio, y migra custom cuando duela lo suficiente.

Si tus tests dependen de servicios muy específicos (drivers para Selenium Grid, browsers legacy), considera AWS Device Farm o un servicio dedicado como BrowserStack. Playwright en CodeBuild cubre el 90% pero no el 100% de casos.

En el próximo artículo: bundle splitting guiado por métricas reales de CloudWatch RUM. Cómo dejar de adivinar qué chunks crear y usar datos de usuarios reales para decidir la arquitectura de tus bundles.

Route Handlers de Next.js vs API Gateway, comparación con números reales

Gustavo Ramirez — Sun, 28 Dec 2025 14:00:00 +0000

Cuando arranco un proyecto nuevo con Next.js en AWS, siempre me hago la misma pregunta. ¿Uso Route Handlers (los archivos route.ts dentro de app/api) o monto un API Gateway separado con Lambdas independientes? Ambos caminos funcionan, pero tienen implicaciones muy distintas en costo, operaciones y escalabilidad.

Este artículo es el resumen de decisiones que tomé en 3 proyectos reales, con los números de costo, latencia y complejidad operacional. La respuesta corta: para la mayoría de apps, Route Handlers son suficientes. Para casos específicos, API Gateway gana. Voy a ser específico sobre cuáles.

Qué es cada uno realmente

Route Handlers son funciones HTTP que Next.js expone como endpoints. Viven en app/api/*/route.ts y se bundlean con el resto de la aplicación. Cuando despliegas Next.js en Lambda vía Amplify Gen 2 o SST, el mismo Lambda que renderiza páginas también atiende los Route Handlers. Una sola función, múltiples responsabilidades.

// app/api/users/route.ts
import { NextResponse } from "next/server";
import { db } from "@/lib/db";

export async function GET() {
  const users = await db.user.findMany();
  return NextResponse.json(users);
}

export async function POST(req: Request) {
  const body = await req.json();
  const user = await db.user.create({ data: body });
  return NextResponse.json(user, { status: 201 });
}

API Gateway es un servicio separado que enruta requests HTTP a Lambdas específicas. Cada endpoint puede ser su propia Lambda con su propio bundle, su propia memoria, su propio timeout.

// cdk/lib/api-stack.ts
import { RestApi, LambdaIntegration } from "aws-cdk-lib/aws-apigateway";
import { Function, Runtime, Code } from "aws-cdk-lib/aws-lambda";

const api = new RestApi(this, "Api");

const getUsersFn = new Function(this, "GetUsers", {
  runtime: Runtime.NODEJS_20_X,
  handler: "index.handler",
  code: Code.fromAsset("lambdas/get-users"),
  memorySize: 512,
});

api.root
  .addResource("users")
  .addMethod("GET", new LambdaIntegration(getUsersFn));

La diferencia clave: Route Handlers viven dentro de tu aplicación Next.js. API Gateway vive fuera, como un producto AWS separado que cualquier cliente puede consumir.

Comparativa de costos reales

Estas mediciones son de un proyecto real con tráfico de 2M requests/mes, distribuidos entre páginas SSR y endpoints JSON.

flowchart LR
    subgraph "Opción A - todo en Next.js Lambda"
      A[CloudFront] --> AL[Lambda Next.js 1GB]
      AL --> AD[Render pages]
      AL --> AR[Route Handlers]
    end

    subgraph "Opción B - split con API Gateway"
      B[CloudFront] --> BL[Lambda Next.js 1GB]
      BL --> BD[Render pages]
      B --> BG[API Gateway]
      BG --> BF1[Lambda users 256MB]
      BG --> BF2[Lambda orders 512MB]
      BG --> BF3[Lambda reports 1GB]
    end

Con los números reales del proyecto:

Componente	Opción A (todo Next.js)	Opción B (split)
Lambda Next.js invocations	2M x $0.20/M = $0.40	500K x $0.20/M = $0.10
Lambda Next.js duration	2M x 1GB x 150ms = $50	500K x 1GB x 200ms = $16.67
API Gateway requests	$0	1.5M x $3.50/M = $5.25
Lambdas específicas	$0	~$18 (mix de memoria/duración)
CloudWatch logs	$12	$18 (más Lambdas, más logs)
Total mensual	$62.40	$58.02

Con este volumen, la diferencia es mínima. La cosa cambia en los extremos. Para tráfico chico (100K requests/mes), Opción A es obviamente más barata porque API Gateway cobra por request desde el primer uso. Para tráfico grande (50M/mes), Opción B empieza a ganar porque puedes ajustar memoria y timeout de cada Lambda a lo que realmente necesita.

Cuándo Route Handlers ganan

1. Proyectos pequeños a medianos.
Si estás arrancando, Route Handlers son menos código, menos infra, menos cosas que se pueden romper. Todo vive en el mismo repo, mismo deploy, mismo CloudWatch log group.

2. Endpoints que comparten código con Server Components.
Si tu Server Component y tu Route Handler llaman a la misma función de lib/db.ts, mantenerlos en el mismo bundle evita duplicación. Con API Gateway separado tendrías que publicar ese código como layer o paquete compartido.

3. Cuando necesitas cookies de sesión disponibles en ambos.
Los Route Handlers heredan el contexto de cookies de Next.js. Los Lambdas detrás de API Gateway no saben nada del sistema de auth de Next.js a menos que implementes el parseo tú mismo.

// app/api/profile/route.ts
import { getSession } from "@/lib/session";

export async function GET() {
  const session = await getSession();
  if (!session) {
    return Response.json({ error: "unauthorized" }, { status: 401 });
  }
  // lógica con session.userId
}

Eso Just Works™. En API Gateway separado, tendrías que parsear la cookie sid, consultar Redis o tu store de sesiones, y eso se vuelve repetitivo.

4. Prototipado rápido.
Agregar un endpoint nuevo en Next.js es crear un archivo. En API Gateway es modificar CDK/Terraform, generar un nuevo bundle, configurar IAM, etc. Para iteración rápida con stakeholders, Route Handlers ganan por velocidad.

Cuándo API Gateway gana

1. Endpoints con perfil muy distinto al resto de la app.
Supongamos que tienes un endpoint que procesa PDFs. Necesita 3GB de RAM, timeout de 60 segundos, y solo se invoca 100 veces al día. Meterlo en el Lambda de Next.js significa que TODO el Lambda tiene 3GB, incluyendo los requests que solo renderizan una página de login. Despilfarro puro.

// lambdas/process-pdf/index.ts
import { S3Event } from "aws-lambda";

export const handler = async (event: S3Event) => {
  // procesamiento pesado de PDF
  // necesita 3GB RAM, 60s timeout
};

Separar esa lógica en un Lambda dedicado detrás de API Gateway te permite pagar solo por lo que usas en esos casos específicos.

2. APIs públicas consumidas por terceros.
Si construyes una API que clientes externos van a consumir (ej: webhooks que dispararon integradores, API pública de tu SaaS), API Gateway te da features clave: API keys, throttling, usage plans, WAF integration, request/response transformation. Route Handlers no tienen nada de eso nativamente.

3. Cuando necesitas múltiples entornos runtime.
Route Handlers corren en Node.js (o Edge Runtime con limitaciones). Si tienes un endpoint que necesita Python para usar una librería específica (OpenCV, scikit-learn), necesitas Lambda separado con Python runtime. API Gateway lo enruta sin problema.

4. Cuando el tráfico de API es mucho mayor que el tráfico de páginas.
Si tu app es 90% API y 10% pages, tiene sentido que el API tenga su propia infra optimizada. Route Handlers en el Lambda de Next.js cargan todo el bundle incluyendo React, dependencias de rendering, etc. Un Lambda dedicado al API puede ser 10x más pequeño y frío menos.

Una arquitectura híbrida real

El patrón que uso en proyectos medianos a grandes: Route Handlers para lo que es parte del user flow normal, API Gateway para lo que es pesado, externo, o con perfil distinto.

flowchart TB
    U[Usuario] --> CF[CloudFront]

    CF -->|páginas + API usuarios| NL[Lambda Next.js]
    NL --> NA[Route Handlers /api/users, /api/projects]
    NL --> NR[Render SSR]

    CF -->|rutas específicas| AG[API Gateway]
    AG --> PF[Lambda Process PDF 3GB]
    AG --> RF[Lambda Reports 1GB]
    AG --> WH[Lambda Webhooks 256MB]

    NL --> DB[(DynamoDB)]
    PF --> DB
    RF --> DB
    WH --> DB

En un proyecto SaaS reciente:

80% del tráfico pasa por Next.js Lambda (pages + Route Handlers típicos)
15% va a /api/reports/* en API Gateway (Lambda 1GB con 30s timeout)
5% va a /api/webhooks/* también en API Gateway (Lambda 256MB muy rápido)

El CloudFront routing se configura con behaviors:

// cdk/lib/cloudfront-stack.ts
const distribution = new Distribution(this, "Distribution", {
  defaultBehavior: {
    origin: new HttpOrigin(nextjsLambdaUrl),
    cachePolicy: CachePolicy.CACHING_DISABLED,
  },
  additionalBehaviors: {
    "/api/reports/*": {
      origin: new RestApiOrigin(reportsApi),
      cachePolicy: CachePolicy.CACHING_DISABLED,
    },
    "/api/webhooks/*": {
      origin: new RestApiOrigin(webhooksApi),
      cachePolicy: CachePolicy.CACHING_DISABLED,
      allowedMethods: AllowedMethods.ALLOW_ALL,
    },
    "/_next/static/*": {
      origin: new S3Origin(staticBucket),
      cachePolicy: CachePolicy.CACHING_OPTIMIZED,
    },
  },
});

CloudFront decide a dónde ir según el path. Para el cliente es transparente, todos los endpoints viven bajo el mismo dominio.

Route Handlers con streaming

Una feature que a menudo se olvida: los Route Handlers pueden hacer streaming con Lambda Response Streaming, igual que las pages.

// app/api/export/route.ts
import { db } from "@/lib/db";

export async function GET() {
  const encoder = new TextEncoder();
  const stream = new ReadableStream({
    async start(controller) {
      controller.enqueue(encoder.encode("id,name,email\n"));

      let cursor: string | undefined;
      do {
        const batch = await db.user.findMany({
          take: 1000,
          skip: cursor ? 1 : 0,
          cursor: cursor ? { id: cursor } : undefined,
          orderBy: { id: "asc" },
        });

        for (const user of batch) {
          controller.enqueue(
            encoder.encode(`${user.id},${user.name},${user.email}\n`)
          );
        }

        cursor = batch[batch.length - 1]?.id;
        if (batch.length < 1000) break;
      } while (cursor);

      controller.close();
    },
  });

  return new Response(stream, {
    headers: {
      "Content-Type": "text/csv",
      "Content-Disposition": "attachment; filename=users.csv",
    },
  });
}

Esto exporta 100K usuarios sin cargar todos en memoria ni esperar 30s antes de empezar a enviar bytes. En Lambda con Response Streaming habilitado, funciona hasta 15 minutos de duración.

API Gateway REST no soporta streaming. Si necesitas streams, HTTP API (v2) o Function URLs sí lo soportan.

Monitoreo comparativo

Un punto que no se discute mucho: cómo ves qué está pasando en producción.

Con Route Handlers, todos los requests (pages + API) van al mismo CloudWatch log group del Lambda de Next.js. Filtrar por endpoint requiere queries en CloudWatch Logs Insights:

fields @timestamp, @message
| filter @message like /\/api\/users/
| stats count() by bin(5m)

Con API Gateway separado, cada Lambda tiene su log group. API Gateway además emite métricas nativas (4xx, 5xx, latencia p50/p95/p99) sin instrumentación. Integración con CloudWatch Metrics es directa.

Para observabilidad fina, la Opción B gana claro. Para observabilidad básica, Opción A es suficiente.

Lo que aprendí aplicando esto

1. Empiezo siempre con Route Handlers.
Migro a API Gateway solo cuando hay un motivo claro. En 3 de 5 proyectos recientes nunca hice esa migración porque nunca apareció el motivo. Premature architecture es peor que refactor después.

2. Los Route Handlers heredan los cold starts del Lambda de Next.js.
Si tu Lambda de Next.js pesa 80MB con todas las dependencias, cada cold start de un Route Handler paga ese arranque. Para APIs críticas con requisito de latencia baja, un Lambda dedicado con bundle de 5MB tiene cold starts más cortos.

3. Las funciones serverless de CDK son más fáciles de testear.
Un Lambda independiente se testea unitariamente sin levantar Next.js. Los Route Handlers son funciones Next.js con todo el contexto; testearlos requiere mocks de cookies(), headers(), etc. Para lógica de negocio compleja, separarla a Lambda dedicada y testear a fondo compensa.

4. El vendor lock-in es diferente.
Route Handlers son Next.js. Si decides cambiar a Remix, Astro o lo que sea, tienes que reescribirlos (aunque la lógica se porta). API Gateway + Lambda es AWS, pero es AWS genérico. Puedes mover el frontend sin tocar los APIs.

5. El costo real depende del perfil de tráfico.
Hice cálculos asumiendo distribución uniforme. Si tu tráfico es bursty (ej: picos por email campaigns), API Gateway throttling te protege mejor que confiar en el Lambda provisioned concurrency de Next.js.

6. Los timeouts son diferentes por default.
Amplify Gen 2 da 30s al Lambda de Next.js. API Gateway REST tiene hard limit de 29s. Si tu endpoint debe correr más, necesitas Function URLs con streaming o mover la operación a background (SQS + Lambda).

Cuándo NO elegir ninguna de las dos

Si tu necesidad es tráfico mínimo con latencia baja garantizada (dashboards internos con 10 usuarios), Next.js puede ser overkill. Un Cloudflare Worker o Deno Deploy sale más barato y frío menos.

Si tus endpoints son esencialmente consultas GraphQL, AppSync con resolvers directos a DynamoDB es más eficiente que cualquier de los dos.

Si tu app tiene tanta lógica server que Next.js se siente forzado, considera un backend separado (NestJS, Go, lo que quieras) detrás de ALB o API Gateway, y Next.js solo hace frontend.

En el próximo artículo: cómo correr Playwright en AWS CodeBuild con contenedores custom para E2E serio. Configuración de browsers, paralelismo real, y artefactos que sirvan para debuggear fallas de tests de producción.

AWS Toolkit para VS Code las funcionalidades que uso todos los dias

Gustavo Ramirez — Thu, 18 Dec 2025 14:00:00 +0000

El AWS Toolkit para VS Code es gratis, oficial, y la mayoría de gente lo instala y lo ignora. Llevo meses usándolo intensivamente y quiero compartir las funcionalidades que de verdad cambiaron mi flujo.

Instalación

Busca "AWS Toolkit" en el marketplace de VS Code. Después configuras tus credenciales:

aws configure sso

Y en VS Code, conectas el perfil desde la barra lateral del Toolkit.

Explorar recursos sin salir del editor

La vista lateral de AWS te deja navegar Lambdas, buckets de S3, tablas de DynamoDB y logs de CloudWatch directamente. Abro un log de CloudWatch en una pestaña como si fuera un archivo local y puedo hacer grep con Ctrl+F normal.

Invocar Lambdas desde el editor

Click derecho sobre una función en la vista de AWS, "Invoke on AWS", le pasas un payload, y ves el resultado en la terminal integrada. No necesitas abrir la consola ni usar el CLI.

Editar código de Lambda en caliente

Puedes descargar el código de una Lambda, editarlo y subirlo sin hacer deploy completo. No es la práctica que recomiendo para producción, pero para entender qué está haciendo una Lambda heredada que nadie documentó, es oro.

Amazon Q integrado

Desde la actualización más reciente, Amazon Q vive dentro del Toolkit. Lo uso para:

Explicar fragmentos de CloudFormation o CDK que no entiendo.
Generar políticas IAM a partir de descripciones.
Traducir código de SAM a CDK cuando migro.

No reemplaza tu criterio, pero acelera tareas repetitivas.

Debug local de SAM

Si tienes un proyecto SAM, el Toolkit te agrega configuraciones de debug automáticamente. Le pones un breakpoint a tu handler de Lambda, presionas F5, y VS Code ejecuta sam local invoke por debajo con el debugger conectado.

Esto cambia completamente cómo depuro Lambdas. Antes era console.log hasta encontrar el problema. Ahora puedo pausar la ejecución y revisar el estado.

IAM Policy Checks

Cuando editas archivos de políticas IAM, el Toolkit te avisa si tu política es muy permisiva o tiene errores. No reemplaza una revisión seria de seguridad, pero detecta los casos obvios antes de desplegar.

Lo que no uso

La creación de recursos desde el Toolkit. Prefiero usar CDK o SAM directamente. La UI está bien para explorar, no para crear.

Cierre

Si escribes código para AWS y no tienes el Toolkit instalado, estás dejando productividad sobre la mesa. Es un viernes productivo el que dedicas a aprenderte los atajos.

Optimización de imágenes on-demand con Lambda, Sharp y CloudFront

Gustavo Ramirez — Tue, 16 Dec 2025 14:00:00 +0000

El cliente pagaba 650 USD al mes a Cloudinary por transformaciones de imagen. Catálogo de e-commerce con 18 mil productos, cada uno con 4 variantes (thumbnail, mobile, desktop, zoom) y 3 formatos (jpg, webp, avif). Armé el mismo flujo con Lambda + Sharp + CloudFront y cuesta 55 USD al mes. Funciona igual de bien y es más flexible.

Acá va la implementación completa.

Arquitectura

flowchart LR
    B[Browser] -->|/img/cat/800x600.webp| CF[CloudFront]
    CF -->|cache miss| LF[Lambda@Edge<br/>viewer-request]
    LF --> S3[S3 Transformed]
    S3 -->|404| APIGW[API Gateway]
    APIGW --> L[Lambda Sharp]
    L --> SO[S3 Original]
    L -->|put transformed| S3
    L --> CF
    S3 --> CF
    CF --> B

La idea es generar transformaciones on-demand la primera vez que alguien las pide. El path de la URL describe la transformación: /img/product-123/800x600.webp. Si S3 ya tiene esa versión, CloudFront la sirve. Si no, Lambda la genera, la guarda en S3 y la devuelve.

URL pattern

Establecí convenciones en la URL para no pasar query params (que complican el caché):

/img/{originalKey}/{width}x{height}.{format}
/img/{originalKey}/{width}x{height}_q{quality}.{format}
/img/{originalKey}/{width}x{height}_fit_{mode}.{format}

Ejemplos:
/img/products/shoe-123.jpg/800x600.webp
/img/products/shoe-123.jpg/400x400_q85.avif
/img/products/shoe-123.jpg/1200x800_fit_cover.webp

CloudFront cachea por URL completa, así cada variante tiene su propia cache entry.

Lambda de transformación

// transformer/index.ts
import { APIGatewayProxyHandlerV2 } from 'aws-lambda';
import { S3Client, GetObjectCommand, PutObjectCommand } from '@aws-sdk/client-s3';
import sharp from 'sharp';

const s3 = new S3Client({ region: process.env.AWS_REGION });
const ORIGINAL_BUCKET = process.env.ORIGINAL_BUCKET!;
const TRANSFORMED_BUCKET = process.env.TRANSFORMED_BUCKET!;

interface TransformParams {
  originalKey: string;
  width: number;
  height: number;
  format: 'webp' | 'avif' | 'jpeg' | 'png';
  quality: number;
  fit: 'cover' | 'contain' | 'fill' | 'inside' | 'outside';
}

function parsePath(path: string): TransformParams | null {
  const match = path.match(
    /^\/img\/(.+)\/(\d+)x(\d+)(?:_q(\d+))?(?:_fit_(\w+))?\.(webp|avif|jpe?g|png)$/
  );
  if (!match) return null;

  const [, originalKey, w, h, q, fit, fmt] = match;
  const width = parseInt(w, 10);
  const height = parseInt(h, 10);

  if (width < 1 || width > 4000 || height < 1 || height > 4000) return null;

  return {
    originalKey: decodeURIComponent(originalKey),
    width,
    height,
    format: (fmt === 'jpg' ? 'jpeg' : fmt) as TransformParams['format'],
    quality: q ? parseInt(q, 10) : 82,
    fit: (fit || 'cover') as TransformParams['fit'],
  };
}

async function transformImage(params: TransformParams): Promise<Buffer> {
  const original = await s3.send(
    new GetObjectCommand({
      Bucket: ORIGINAL_BUCKET,
      Key: params.originalKey,
    })
  );
  const originalBuffer = Buffer.from(await original.Body!.transformToByteArray());

  let pipeline = sharp(originalBuffer, { failOn: 'error' }).resize({
    width: params.width,
    height: params.height,
    fit: params.fit,
    withoutEnlargement: true,
  });

  switch (params.format) {
    case 'webp':
      pipeline = pipeline.webp({ quality: params.quality, effort: 4 });
      break;
    case 'avif':
      pipeline = pipeline.avif({ quality: params.quality, effort: 4 });
      break;
    case 'jpeg':
      pipeline = pipeline.jpeg({ quality: params.quality, progressive: true, mozjpeg: true });
      break;
    case 'png':
      pipeline = pipeline.png({ compressionLevel: 9, palette: true });
      break;
  }

  return pipeline.toBuffer();
}

export const handler: APIGatewayProxyHandlerV2 = async (event) => {
  const path = event.rawPath;
  const params = parsePath(path);

  if (!params) {
    return {
      statusCode: 400,
      body: JSON.stringify({ error: 'Invalid URL pattern' }),
    };
  }

  try {
    const transformed = await transformImage(params);
    const transformedKey = path.substring(1);

    await s3.send(
      new PutObjectCommand({
        Bucket: TRANSFORMED_BUCKET,
        Key: transformedKey,
        Body: transformed,
        ContentType: `image/${params.format}`,
        CacheControl: 'public, max-age=31536000, immutable',
      })
    );

    return {
      statusCode: 200,
      headers: {
        'Content-Type': `image/${params.format}`,
        'Cache-Control': 'public, max-age=31536000, immutable',
      },
      body: transformed.toString('base64'),
      isBase64Encoded: true,
    };
  } catch (err) {
    console.error('Transform failed:', err);
    if ((err as any).Code === 'NoSuchKey') {
      return { statusCode: 404, body: 'Original not found' };
    }
    return { statusCode: 500, body: 'Transform error' };
  }
};

El failOn: 'error' es importante. Sharp por defecto intenta procesar imágenes corruptas y puede tardar mucho o consumir memoria. Mejor fallar rápido y devolver 500.

El withoutEnlargement: true evita escalar imágenes pequeñas hacia arriba. Si la original es 500x500 y piden 1000x1000, devuelve 500x500. Los clientes pueden escalar con CSS.

Sharp en Lambda

Sharp tiene binarios nativos compilados por plataforma. En Lambda necesitas el build de Linux x64 o ARM64. El truco:

// package.json en el directorio del Lambda
{
  "dependencies": {
    "sharp": "0.33.2"
  }
}

# build script
cd lambdas/transformer
rm -rf node_modules
npm install --os=linux --cpu=arm64 sharp
zip -r ../transformer.zip .

Si olvidas el --os=linux, sharp se instala para macOS y el Lambda falla con "something.node: invalid ELF header".

La otra opción es usar ARM64 Graviton en Lambda. Es 20% más barato y lo soporté sin problemas. architecture: Architecture.ARM_64 en CDK.

CDK stack completo

// cdk/image-stack.ts
import * as cdk from 'aws-cdk-lib';
import * as lambda from 'aws-cdk-lib/aws-lambda';
import * as apigwv2 from 'aws-cdk-lib/aws-apigatewayv2';
import * as integrations from 'aws-cdk-lib/aws-apigatewayv2-integrations';
import * as s3 from 'aws-cdk-lib/aws-s3';
import * as cloudfront from 'aws-cdk-lib/aws-cloudfront';
import * as origins from 'aws-cdk-lib/aws-cloudfront-origins';
import { Construct } from 'constructs';

export class ImageOptimizationStack extends cdk.Stack {
  constructor(scope: Construct, id: string, props: cdk.StackProps) {
    super(scope, id, props);

    const originalBucket = new s3.Bucket(this, 'OriginalImages', {
      encryption: s3.BucketEncryption.S3_MANAGED,
      versioned: true,
    });

    const transformedBucket = new s3.Bucket(this, 'TransformedImages', {
      encryption: s3.BucketEncryption.S3_MANAGED,
      lifecycleRules: [
        {
          id: 'expire-rare-variants',
          prefix: 'img/',
          transitions: [
            {
              storageClass: s3.StorageClass.INTELLIGENT_TIERING,
              transitionAfter: cdk.Duration.days(1),
            },
          ],
        },
      ],
    });

    const transformerFn = new lambda.Function(this, 'TransformerFn', {
      runtime: lambda.Runtime.NODEJS_20_X,
      handler: 'index.handler',
      code: lambda.Code.fromAsset('../lambdas/transformer.zip'),
      architecture: lambda.Architecture.ARM_64,
      memorySize: 1024,
      timeout: cdk.Duration.seconds(15),
      environment: {
        ORIGINAL_BUCKET: originalBucket.bucketName,
        TRANSFORMED_BUCKET: transformedBucket.bucketName,
      },
    });

    originalBucket.grantRead(transformerFn);
    transformedBucket.grantReadWrite(transformerFn);

    const httpApi = new apigwv2.HttpApi(this, 'TransformerApi', {
      defaultIntegration: new integrations.HttpLambdaIntegration(
        'TransformerIntegration',
        transformerFn
      ),
    });

    const distribution = new cloudfront.Distribution(this, 'ImageDistribution', {
      defaultBehavior: {
        origin: origins.OriginGroup.fromOrigins({
          primaryOrigin: new origins.S3Origin(transformedBucket),
          fallbackOrigin: new origins.HttpOrigin(
            cdk.Fn.select(2, cdk.Fn.split('/', httpApi.apiEndpoint))
          ),
          fallbackStatusCodes: [403, 404],
        }),
        cachePolicy: cloudfront.CachePolicy.CACHING_OPTIMIZED,
        viewerProtocolPolicy: cloudfront.ViewerProtocolPolicy.REDIRECT_TO_HTTPS,
        compress: true,
      },
      priceClass: cloudfront.PriceClass.PRICE_CLASS_100,
    });

    new cdk.CfnOutput(this, 'ImageCdnUrl', {
      value: distribution.distributionDomainName,
    });
  }
}

El OriginGroup es la magia. CloudFront intenta primero S3 (donde están los transformados). Si devuelve 404 o 403 (porque aún no existe), cae al API Gateway con el Lambda que genera la imagen.

La Lambda guarda el resultado en S3 mientras devuelve el response. La siguiente request para la misma URL va directo a S3, sin volver a invocar Lambda.

Componente Picture responsive

// components/SmartImage.tsx
interface SmartImageProps {
  src: string;
  alt: string;
  widths: number[];
  aspectRatio?: number;
  className?: string;
  priority?: boolean;
}

const CDN_BASE = 'https://images.ittal.co';

export function SmartImage({
  src,
  alt,
  widths,
  aspectRatio = 16 / 9,
  className,
  priority = false,
}: SmartImageProps) {
  const buildUrl = (width: number, format: string) => {
    const height = Math.round(width / aspectRatio);
    return `${CDN_BASE}/img/${encodeURIComponent(src)}/${width}x${height}.${format}`;
  };

  const avifSrcSet = widths.map((w) => `${buildUrl(w, 'avif')} ${w}w`).join(', ');
  const webpSrcSet = widths.map((w) => `${buildUrl(w, 'webp')} ${w}w`).join(', ');
  const jpegSrcSet = widths.map((w) => `${buildUrl(w, 'jpeg')} ${w}w`).join(', ');

  const sizes = `(max-width: 640px) 100vw, (max-width: 1024px) 50vw, ${Math.max(...widths)}px`;

  return (
    <picture className={className}>
      <source type="image/avif" srcSet={avifSrcSet} sizes={sizes} />
      <source type="image/webp" srcSet={webpSrcSet} sizes={sizes} />
      <img
        src={buildUrl(widths[0], 'jpeg')}
        srcSet={jpegSrcSet}
        sizes={sizes}
        alt={alt}
        loading={priority ? 'eager' : 'lazy'}
        decoding="async"
        width={widths[0]}
        height={Math.round(widths[0] / aspectRatio)}
      />
    </picture>
  );
}

Uso:

<SmartImage
  src="products/shoe-123.jpg"
  alt="Zapatilla running"
  widths={[400, 800, 1200, 1600]}
  aspectRatio={1}
  priority
/>

Genera 12 URLs (4 widths × 3 formatos). El navegador elige la mejor combinación según soporte y viewport. AVIF donde se puede, WebP como fallback, JPEG universal.

Comparativa de formatos

Tomé una foto de producto de 3000x2000 original en JPEG (1.2MB). Al redimensionar a 800x600:

Formato	Calidad	Tamaño	Tiempo Lambda	Soporte
JPEG	82	95 KB	180 ms	100%
WebP	82	55 KB	210 ms	97%
AVIF	82	30 KB	850 ms	88%

AVIF tarda 4x más en generarse pero solo se genera una vez. Después S3 lo sirve instantáneo. El ahorro de bandwidth compensa el costo de Lambda.

Lo que aprendí

1. Memoria de Lambda importa más que tiempo.
Sharp usa mucha RAM para imágenes grandes. Con 512MB fallaba en imágenes 4K. Con 1024MB funciona. Cada duplicar de memoria también duplica CPU, así que 1024MB es 2x más rápido que 512MB aunque pagues el doble por ms.

2. Lambda cold start es brutal con Sharp.
Cold start con Sharp tarda 2-3 segundos (load del binario nativo). Con provisioned concurrency (2 instancias) bajé a 400ms. Para 30 USD/mes vale la pena en sitios con tráfico medio.

3. No optimices imágenes pequeñas.
Si la original pesa 20KB, no la transformes. El overhead de la Lambda (100ms) + el tiempo de red probablemente sean más que el benefit. Agregué un bypass en el Lambda: si originalSize < 50KB, devuelvo la original sin procesar.

4. Sharp tiene bug con EXIF orientation.
Fotos de iPhone vienen con orientation en EXIF (la foto real está rotada 90 grados, el metadata dice "rotate 270"). Sin .rotate() antes del resize, se ven giradas. La llamada .rotate() sin parámetros aplica el EXIF.

5. Lifecycle en S3 me ahorró 80% de storage.
Tenía 2TB de variantes transformadas, muchas generadas una sola vez para un bot que nunca volvió. Movi todo a Intelligent Tiering después de 1 día. Las variantes populares se quedan en Standard, las raras bajan a Infrequent Access automáticamente. Ahorro: 40 USD al mes.

Cuándo NO implementar esto tú mismo

Si tu volumen es pequeño (menos de 100 productos), Cloudinary Free o Imgix Free cubren sin problemas. El ROI de esta infra no existe para catálogos chicos.

Si tu equipo no tiene experiencia con Lambda, el debugging de Sharp puede ser frustrante. Los errores de binarios nativos son crípticos. Cloudinary paga por eliminarte ese dolor.

Si necesitas transformaciones avanzadas (face detection, auto crop inteligente, filtros AI), Cloudinary y Imgix tienen features que Sharp no. Para eso, paga el servicio.

El próximo artículo compara Route Handlers de Next.js 15 contra API Gateway. Cuándo cada uno gana, cuánto cuestan, y por qué a veces vale la pena combinarlos.

Dashboards realtime con API Gateway WebSockets, React y DynamoDB Streams

Gustavo Ramirez — Thu, 04 Dec 2025 14:00:00 +0000

Un cliente de logística me pidió convertir su dashboard de flota de pooling cada 10 segundos a tiempo real. Tenían 40 operadores mirando 800 vehículos simultáneos. Su factura de API Gateway REST estaba en 1200 USD al mes solo por el polling. Migré a WebSockets con API Gateway WS y DynamoDB Streams. Factura bajó a 180 USD y los updates llegan en menos de 200ms.

Comparto la arquitectura completa.

Arquitectura

flowchart LR
    V[Vehicles<br/>GPS pings] --> IoT[AWS IoT Core]
    IoT --> DDB[(DynamoDB<br/>Vehicle state)]
    DDB --> Stream[DynamoDB Stream]
    Stream --> Fanout[Lambda Fanout]
    Fanout --> APIGW[API Gateway<br/>WebSocket API]
    APIGW --> Browsers[React Dashboards]
    Fanout --> Conns[(DynamoDB<br/>Connections)]

El flujo tiene dos partes. Los vehículos envían GPS a IoT Core, IoT escribe en DynamoDB. Cuando cambia un registro, DynamoDB Stream dispara una Lambda que decide a quién notificar. Esa Lambda mira una tabla de connections (quién está conectado, qué filtros tiene) y manda el update por WebSocket.

Setup del WebSocket API

No hay construct de alto nivel en CDK para WebSocket API. Hay que usar los L1:

// cdk/websocket-stack.ts
import * as cdk from 'aws-cdk-lib';
import * as apigwv2 from 'aws-cdk-lib/aws-apigatewayv2';
import * as integrations from 'aws-cdk-lib/aws-apigatewayv2-integrations';
import * as lambda from 'aws-cdk-lib/aws-lambda';
import * as dynamodb from 'aws-cdk-lib/aws-dynamodb';
import { Construct } from 'constructs';

export class WebsocketStack extends cdk.Stack {
  constructor(scope: Construct, id: string, props: cdk.StackProps) {
    super(scope, id, props);

    const connectionsTable = new dynamodb.Table(this, 'Connections', {
      partitionKey: { name: 'connectionId', type: dynamodb.AttributeType.STRING },
      billingMode: dynamodb.BillingMode.PAY_PER_REQUEST,
      timeToLiveAttribute: 'ttl',
    });

    connectionsTable.addGlobalSecondaryIndex({
      indexName: 'userId-index',
      partitionKey: { name: 'userId', type: dynamodb.AttributeType.STRING },
    });

    const vehiclesTable = new dynamodb.Table(this, 'Vehicles', {
      partitionKey: { name: 'vehicleId', type: dynamodb.AttributeType.STRING },
      billingMode: dynamodb.BillingMode.PAY_PER_REQUEST,
      stream: dynamodb.StreamViewType.NEW_AND_OLD_IMAGES,
    });

    const connectFn = new lambda.Function(this, 'ConnectFn', {
      runtime: lambda.Runtime.NODEJS_20_X,
      handler: 'connect.handler',
      code: lambda.Code.fromAsset('../lambdas/connect'),
      environment: {
        CONNECTIONS_TABLE: connectionsTable.tableName,
      },
    });
    connectionsTable.grantWriteData(connectFn);

    const disconnectFn = new lambda.Function(this, 'DisconnectFn', {
      runtime: lambda.Runtime.NODEJS_20_X,
      handler: 'disconnect.handler',
      code: lambda.Code.fromAsset('../lambdas/disconnect'),
      environment: {
        CONNECTIONS_TABLE: connectionsTable.tableName,
      },
    });
    connectionsTable.grantWriteData(disconnectFn);

    const subscribeFn = new lambda.Function(this, 'SubscribeFn', {
      runtime: lambda.Runtime.NODEJS_20_X,
      handler: 'subscribe.handler',
      code: lambda.Code.fromAsset('../lambdas/subscribe'),
      environment: {
        CONNECTIONS_TABLE: connectionsTable.tableName,
      },
    });
    connectionsTable.grantReadWriteData(subscribeFn);

    const wsApi = new apigwv2.WebSocketApi(this, 'FleetWsApi', {
      connectRouteOptions: {
        integration: new integrations.WebSocketLambdaIntegration(
          'ConnectIntegration',
          connectFn
        ),
      },
      disconnectRouteOptions: {
        integration: new integrations.WebSocketLambdaIntegration(
          'DisconnectIntegration',
          disconnectFn
        ),
      },
    });

    wsApi.addRoute('subscribe', {
      integration: new integrations.WebSocketLambdaIntegration(
        'SubscribeIntegration',
        subscribeFn
      ),
    });

    const wsStage = new apigwv2.WebSocketStage(this, 'FleetStage', {
      webSocketApi: wsApi,
      stageName: 'prod',
      autoDeploy: true,
    });

    const fanoutFn = new lambda.Function(this, 'FanoutFn', {
      runtime: lambda.Runtime.NODEJS_20_X,
      handler: 'fanout.handler',
      code: lambda.Code.fromAsset('../lambdas/fanout'),
      environment: {
        CONNECTIONS_TABLE: connectionsTable.tableName,
        WS_ENDPOINT: `${wsApi.apiEndpoint}/${wsStage.stageName}`,
      },
      timeout: cdk.Duration.seconds(30),
    });

    connectionsTable.grantReadData(fanoutFn);
    wsApi.grantManageConnections(fanoutFn);

    fanoutFn.addEventSource(
      new cdk.aws_lambda_event_sources.DynamoEventSource(vehiclesTable, {
        startingPosition: lambda.StartingPosition.LATEST,
        batchSize: 100,
        retryAttempts: 3,
      })
    );
  }
}

Lambda de conexión

// lambdas/connect/connect.ts
import { APIGatewayProxyWebsocketEventV2 } from 'aws-lambda';
import { DynamoDBClient } from '@aws-sdk/client-dynamodb';
import { DynamoDBDocumentClient, PutCommand } from '@aws-sdk/lib-dynamodb';
import jwt from 'jsonwebtoken';
import jwksClient from 'jwks-rsa';

const ddb = DynamoDBDocumentClient.from(new DynamoDBClient({}));
const jwks = jwksClient({
  jwksUri: `https://cognito-idp.us-east-1.amazonaws.com/${process.env.USER_POOL_ID}/.well-known/jwks.json`,
});

function getKey(header: jwt.JwtHeader, callback: jwt.SigningKeyCallback) {
  jwks.getSigningKey(header.kid, (err, key) => {
    if (err) return callback(err);
    callback(null, key!.getPublicKey());
  });
}

function verifyToken(token: string): Promise<jwt.JwtPayload> {
  return new Promise((resolve, reject) => {
    jwt.verify(token, getKey, { algorithms: ['RS256'] }, (err, decoded) => {
      if (err) reject(err);
      else resolve(decoded as jwt.JwtPayload);
    });
  });
}

export const handler = async (event: APIGatewayProxyWebsocketEventV2) => {
  const connectionId = event.requestContext.connectionId!;
  const token = event.queryStringParameters?.token;

  if (!token) {
    return { statusCode: 401, body: 'Unauthorized' };
  }

  try {
    const payload = await verifyToken(token);
    const userId = payload.sub as string;
    const tenantId = payload['custom:tenantId'] as string;

    await ddb.send(
      new PutCommand({
        TableName: process.env.CONNECTIONS_TABLE!,
        Item: {
          connectionId,
          userId,
          tenantId,
          subscribedVehicles: [],
          connectedAt: Date.now(),
          ttl: Math.floor(Date.now() / 1000) + 7200,
        },
      })
    );

    return { statusCode: 200, body: 'Connected' };
  } catch (err) {
    console.error('Auth failed:', err);
    return { statusCode: 401, body: 'Invalid token' };
  }
};

El token viene como query string porque WebSockets no soportan headers custom en el handshake. Es un pattern común, documentado y aceptado. El TTL de 2 horas es un cleanup: si algo sale mal y no capturamos el disconnect, DynamoDB borra la entry sola.

Lambda de suscripción

El cliente elige qué vehículos quiere recibir. No le mandamos todos los eventos a todos:

// lambdas/subscribe/subscribe.ts
import { APIGatewayProxyWebsocketEventV2 } from 'aws-lambda';
import { DynamoDBClient } from '@aws-sdk/client-dynamodb';
import { DynamoDBDocumentClient, UpdateCommand } from '@aws-sdk/lib-dynamodb';

const ddb = DynamoDBDocumentClient.from(new DynamoDBClient({}));

interface SubscribeMessage {
  action: 'subscribe';
  vehicleIds: string[];
}

export const handler = async (event: APIGatewayProxyWebsocketEventV2) => {
  const connectionId = event.requestContext.connectionId!;
  const body = JSON.parse(event.body || '{}') as SubscribeMessage;

  if (!Array.isArray(body.vehicleIds) || body.vehicleIds.length > 200) {
    return { statusCode: 400, body: 'Invalid subscription' };
  }

  await ddb.send(
    new UpdateCommand({
      TableName: process.env.CONNECTIONS_TABLE!,
      Key: { connectionId },
      UpdateExpression: 'SET subscribedVehicles = :v',
      ExpressionAttributeValues: {
        ':v': body.vehicleIds,
      },
    })
  );

  return { statusCode: 200, body: JSON.stringify({ subscribed: body.vehicleIds.length }) };
};

El límite de 200 vehículos por conexión es arbitrario pero necesario. Sin límite, un cliente malicioso puede suscribirse a toda la flota y DoS'ear al fanout.

Lambda de fanout

Esta es la pieza con más lógica. Lee el stream de DynamoDB, decide qué conexiones deben recibir qué update, y las envía en paralelo:

// lambdas/fanout/fanout.ts
import { DynamoDBStreamEvent } from 'aws-lambda';
import { DynamoDBClient } from '@aws-sdk/client-dynamodb';
import { DynamoDBDocumentClient, ScanCommand } from '@aws-sdk/lib-dynamodb';
import {
  ApiGatewayManagementApiClient,
  PostToConnectionCommand,
  GoneException,
} from '@aws-sdk/client-apigatewaymanagementapi';
import { unmarshall } from '@aws-sdk/util-dynamodb';

const ddb = DynamoDBDocumentClient.from(new DynamoDBClient({}));
const apigw = new ApiGatewayManagementApiClient({
  endpoint: process.env.WS_ENDPOINT,
});

interface Connection {
  connectionId: string;
  userId: string;
  tenantId: string;
  subscribedVehicles: string[];
}

async function getActiveConnections(): Promise<Connection[]> {
  const result = await ddb.send(
    new ScanCommand({
      TableName: process.env.CONNECTIONS_TABLE!,
    })
  );
  return (result.Items || []) as Connection[];
}

async function sendToConnection(
  connectionId: string,
  payload: unknown
): Promise<boolean> {
  try {
    await apigw.send(
      new PostToConnectionCommand({
        ConnectionId: connectionId,
        Data: Buffer.from(JSON.stringify(payload)),
      })
    );
    return true;
  } catch (err) {
    if (err instanceof GoneException) {
      console.log(`Connection ${connectionId} is gone, should cleanup`);
      return false;
    }
    throw err;
  }
}

export const handler = async (event: DynamoDBStreamEvent) => {
  const connections = await getActiveConnections();
  const updates: { vehicleId: string; data: any; tenantId: string }[] = [];

  for (const record of event.Records) {
    if (record.eventName !== 'MODIFY' && record.eventName !== 'INSERT') continue;
    const newImage = record.dynamodb?.NewImage;
    if (!newImage) continue;
    const item = unmarshall(newImage as any);
    updates.push({
      vehicleId: item.vehicleId,
      data: item,
      tenantId: item.tenantId,
    });
  }

  const sends: Promise<boolean>[] = [];

  for (const update of updates) {
    const interested = connections.filter(
      (conn) =>
        conn.tenantId === update.tenantId &&
        conn.subscribedVehicles.includes(update.vehicleId)
    );

    for (const conn of interested) {
      sends.push(
        sendToConnection(conn.connectionId, {
          type: 'vehicle.update',
          vehicleId: update.vehicleId,
          data: update.data,
        })
      );
    }
  }

  const results = await Promise.allSettled(sends);
  const failed = results.filter((r) => r.status === 'rejected').length;
  console.log(`Sent ${sends.length} messages, ${failed} failed`);
};

El Scan de connections no escala a cientos de miles de conexiones. Para volumen alto, uso el GSI userId-index con queries específicos o muevo a un cache en ElastiCache. En este cliente tenemos 40 conexiones simultáneas, el scan está OK.

Cliente React

// hooks/useVehicleStream.ts
import { useEffect, useRef, useState, useCallback } from 'react';
import { fetchAuthSession } from 'aws-amplify/auth';

interface VehicleState {
  vehicleId: string;
  lat: number;
  lng: number;
  speed: number;
  updatedAt: number;
}

export function useVehicleStream(vehicleIds: string[]) {
  const [vehicles, setVehicles] = useState<Map<string, VehicleState>>(new Map());
  const [status, setStatus] = useState<'disconnected' | 'connecting' | 'connected'>(
    'disconnected'
  );
  const wsRef = useRef<WebSocket | null>(null);
  const reconnectTimeoutRef = useRef<number | null>(null);
  const reconnectAttemptsRef = useRef(0);

  const connect = useCallback(async () => {
    setStatus('connecting');
    const session = await fetchAuthSession();
    const token = session.tokens?.idToken?.toString();
    const wsUrl = `wss://api.fleet.example.com/prod?token=${token}`;

    const ws = new WebSocket(wsUrl);

    ws.onopen = () => {
      setStatus('connected');
      reconnectAttemptsRef.current = 0;
      ws.send(
        JSON.stringify({
          action: 'subscribe',
          vehicleIds,
        })
      );
    };

    ws.onmessage = (event) => {
      try {
        const msg = JSON.parse(event.data);
        if (msg.type === 'vehicle.update') {
          setVehicles((prev) => {
            const next = new Map(prev);
            next.set(msg.vehicleId, msg.data);
            return next;
          });
        }
      } catch (err) {
        console.error('Bad message:', err);
      }
    };

    ws.onerror = (err) => {
      console.error('WebSocket error:', err);
    };

    ws.onclose = () => {
      setStatus('disconnected');
      wsRef.current = null;

      const backoff = Math.min(30000, 1000 * Math.pow(2, reconnectAttemptsRef.current));
      reconnectAttemptsRef.current++;
      reconnectTimeoutRef.current = window.setTimeout(connect, backoff);
    };

    wsRef.current = ws;
  }, [vehicleIds]);

  useEffect(() => {
    connect();
    return () => {
      if (reconnectTimeoutRef.current) {
        clearTimeout(reconnectTimeoutRef.current);
      }
      wsRef.current?.close();
    };
  }, [connect]);

  useEffect(() => {
    if (status === 'connected' && wsRef.current) {
      wsRef.current.send(
        JSON.stringify({
          action: 'subscribe',
          vehicleIds,
        })
      );
    }
  }, [vehicleIds, status]);

  return { vehicles, status };
}

Exponential backoff para reconexiones, resuscripción automática cuando cambian los vehicleIds, cleanup del timeout en unmount. Detalles que se olvidan fácil y te muerden en producción.

Comparativa de costos

Para 40 usuarios conectados 8h al día, 800 vehículos actualizando cada 5 segundos:

Arquitectura	Costo mensual	Latencia	Complejidad
REST polling 10s	1200 USD	10s	Baja
Pusher managed	350 USD	300ms	Baja
Socket.io + EC2	200 USD	200ms	Alta
API GW WebSockets	180 USD	200ms	Media
AppSync subscriptions	250 USD	200ms	Media

API Gateway WS cobra 1 USD por millón de mensajes + 0.25 USD por millón de minutos de conexión. Para este tráfico sale muy barato.

Lo que aprendí

1. DynamoDB Streams tiene 2 shards por tabla.
Escalan automáticamente pero el startup es lento. Si tu tabla no ha recibido tráfico en horas, el primer batch tarda más. En horas pico va perfecto.

2. El límite de 128KB por mensaje WebSocket me cacheteó.
Un update de vehículo con su historial de rutas pasaba el límite. Partí el payload en mensajes separados. Regla: mensajes de WebSocket deben ser pequeños, el estado se hidrata por REST y luego solo mandas deltas.

3. API Gateway WS tiene idle timeout de 10 minutos.
Si no hay tráfico en 10 minutos, la conexión se cierra. Implementé heartbeat desde el cliente cada 5 minutos con un {action: 'ping'}. La ruta ping retorna 200 sin hacer nada. Problema resuelto.

4. GoneException significa conexión muerta, hay que limpiar.
Cuando un cliente cierra el browser sin disconnect limpio (mata el proceso, cierra el laptop), la conexión queda zombie en mi tabla. Al intentar enviarle, API Gateway tira GoneException. La Lambda de fanout debería borrar esas entries. Lo hago en un segundo Lambda con SQS para no bloquear el fanout.

5. No pongas lógica pesada en el $connect.
Si $connect tarda más de 30 segundos (timeout de API Gateway WS), la conexión falla. Validé JWT, escribí a DynamoDB, y en casos raros tardaba 35s. Moví la validación de permisos a una Lambda separada llamada en el primer mensaje subscribe.

Cuándo NO usar WebSockets

Si tu update rate es menor a 1 por minuto, polling con HTTP es más simple y barato. WebSockets tiene overhead de mantener conexión.

Si tu frontend es público y masivo (miles de conexiones), considera AppSync con subscriptions (filtros server-side nativos) o incluso EventBridge + SSE (Server-Sent Events) que escalan mejor con CloudFront.

Si tus clientes están detrás de proxies corporativos restrictivos, WebSockets a veces se bloquean. SSE con fallback a long-polling es más resiliente aunque menos eficiente.

El próximo artículo cubre optimización de imágenes on-demand con Lambda y Sharp. Muestro cómo reemplazar Cloudinary con AWS y pagar 50 USD en lugar de 600.

Monorepos NX en CodeBuild con matrices, builds paralelos y caché distribuida

Gustavo Ramirez — Sat, 22 Nov 2025 14:00:00 +0000

Hace meses heredé un monorepo de un cliente de banca con 12 aplicaciones frontend, 8 libraries compartidas y un pipeline que tardaba 42 minutos. Cada push dolía. Lo migré a NX con matrices de CodeBuild y caché distribuida en S3. Hoy el pipeline tarda 8 minutos en el peor caso y 90 segundos cuando solo se toca una librería.

Este artículo es la guía paso a paso de esa migración.

El problema de un monorepo sin herramientas

El setup original era un npm-workspaces con un Jenkinsfile que ejecutaba builds secuenciales:

npm run build:app1
npm run build:app2
...
npm run test:all
npm run e2e:all

Cada app tardaba 3 minutos en buildear. Los tests otros 15 minutos. E2E otros 10. El cuello de botella: nadie sabía qué había cambiado realmente, así que se construía todo siempre.

flowchart TD
    Push[git push] --> Jenkins
    Jenkins --> Build1[Build app1<br/>3 min]
    Build1 --> Build2[Build app2<br/>3 min]
    Build2 --> Build12[Build app12<br/>3 min]
    Build12 --> Test[Tests secuenciales<br/>15 min]
    Test --> E2E[E2E todos<br/>10 min]
    E2E --> Deploy
    style Jenkins fill:#ff6b6b

NX resuelve esto con dos conceptos: el grafo de dependencias y el caché computacional. Sabe qué afectó cada commit y solo ejecuta tareas sobre lo afectado.

Setup de NX en el monorepo

npx nx@latest init

El comando analiza el repo y genera nx.json con detección automática de apps y librerías. Después limpié la configuración a mano:

{
  "$schema": "./node_modules/nx/schemas/nx-schema.json",
  "namedInputs": {
    "default": ["{projectRoot}/**/*", "sharedGlobals"],
    "production": [
      "default",
      "!{projectRoot}/**/*.spec.ts",
      "!{projectRoot}/**/*.test.tsx",
      "!{projectRoot}/jest.config.ts",
      "!{projectRoot}/.eslintrc.json"
    ],
    "sharedGlobals": ["{workspaceRoot}/tsconfig.base.json"]
  },
  "targetDefaults": {
    "build": {
      "dependsOn": ["^build"],
      "inputs": ["production", "^production"],
      "cache": true
    },
    "test": {
      "inputs": ["default", "^production"],
      "cache": true
    },
    "lint": {
      "inputs": ["default"],
      "cache": true
    },
    "e2e": {
      "inputs": ["default", "^production"],
      "cache": true
    }
  },
  "parallel": 4,
  "cacheDirectory": "node_modules/.cache/nx"
}

El namedInputs define qué archivos invalidan el caché. Para build uso production (que excluye tests y config de lint) porque cambiar un test no debería reconstruir la app. Para test uso default (incluye todo) porque cambios en la app afectan sus tests.

Caché distribuida en S3

El caché local de NX funciona en tu máquina. En CI, cada build parte de cero salvo que compartas el caché. Nx Cloud es la solución oficial pero cuesta dinero. S3 sale gratis prácticamente.

Instalé @nx/powerpack-s3-cache:

npm install -D @nx/powerpack-s3-cache

Y configuré el plugin en nx.json:

{
  "s3": {
    "bucket": "ittal-nx-cache",
    "region": "us-east-1",
    "prefix": "monorepo-banca"
  }
}

El plugin usa las credenciales de AWS del ambiente. En CodeBuild ya vienen inyectadas por el IAM role del proyecto. En local uso aws-vault.

Buildspec con matriz de CodeBuild

Aquí está la pieza clave. CodeBuild soporta batch builds con matrices. Ejecuto una fase que calcula qué proyectos están afectados y genera la matriz dinámicamente:

# buildspec.yml principal
version: 0.2

batch:
  fast-fail: true
  build-graph:
    - identifier: detect_affected
      buildspec: buildspec-detect.yml
      env:
        compute-type: BUILD_GENERAL1_SMALL

    - identifier: build_apps
      depend-on:
        - detect_affected
      buildspec: buildspec-build.yml
      env:
        compute-type: BUILD_GENERAL1_MEDIUM
        variables:
          AFFECTED_PROJECTS: ""

    - identifier: test_apps
      depend-on:
        - detect_affected
      buildspec: buildspec-test.yml
      env:
        compute-type: BUILD_GENERAL1_MEDIUM

    - identifier: e2e
      depend-on:
        - build_apps
      buildspec: buildspec-e2e.yml
      env:
        compute-type: BUILD_GENERAL1_LARGE

    - identifier: deploy
      depend-on:
        - test_apps
        - e2e
      buildspec: buildspec-deploy.yml

Fase 1: detectar qué cambió

# buildspec-detect.yml
version: 0.2

phases:
  install:
    runtime-versions:
      nodejs: 20
    commands:
      - npm ci --prefer-offline

  build:
    commands:
      - git fetch origin main
      - export BASE_SHA=$(git merge-base HEAD origin/main)
      - echo "Base SHA for affected calculation: $BASE_SHA"
      - |
        AFFECTED=$(npx nx show projects --affected --base=$BASE_SHA --type=app --json)
        echo "Affected apps: $AFFECTED"
        echo "$AFFECTED" > affected-apps.json
      - |
        AFFECTED_LIBS=$(npx nx show projects --affected --base=$BASE_SHA --type=lib --json)
        echo "Affected libs: $AFFECTED_LIBS"
        echo "$AFFECTED_LIBS" > affected-libs.json

artifacts:
  files:
    - affected-apps.json
    - affected-libs.json
  name: affected-manifest

git merge-base HEAD origin/main me da el commit donde mi branch se separó de main. NX calcula qué proyectos cambiaron desde ese punto. Esto es correcto para pull requests y también para builds de main (donde el base es el commit previo).

Fase 2: build paralelo de afectados

# buildspec-build.yml
version: 0.2

phases:
  install:
    runtime-versions:
      nodejs: 20
    commands:
      - npm ci --prefer-offline

  pre_build:
    commands:
      - aws s3 cp s3://ittal-nx-cache-artifacts/$CODEBUILD_BUILD_NUMBER/affected-apps.json .
      - export AFFECTED_COUNT=$(jq 'length' affected-apps.json)
      - echo "Building $AFFECTED_COUNT affected projects"

  build:
    commands:
      - |
        if [ "$AFFECTED_COUNT" = "0" ]; then
          echo "Nothing affected, skipping build"
          exit 0
        fi
      - npx nx affected --target=build --parallel=4 --configuration=production
      - npx nx affected --target=lint --parallel=4

  post_build:
    commands:
      - |
        for app in $(jq -r '.[]' affected-apps.json); do
          if [ -d "dist/apps/$app" ]; then
            echo "Uploading $app artifacts"
            aws s3 sync dist/apps/$app s3://ittal-build-artifacts/$CODEBUILD_BUILD_NUMBER/$app/
          fi
        done

cache:
  paths:
    - 'node_modules/**/*'
    - 'node_modules/.cache/nx/**/*'

Con --parallel=4 construyo hasta 4 apps simultáneamente en una instancia MEDIUM (4 vCPU, 7GB RAM). Para el monorepo actual es suficiente. Si creciera a 30 apps, saltaría a LARGE con paralelismo 8.

Fase 3: tests con split automático

NX soporta distribución de tests entre agents. Para un solo agent es fácil:

# buildspec-test.yml
version: 0.2

phases:
  install:
    runtime-versions:
      nodejs: 20
    commands:
      - npm ci --prefer-offline

  build:
    commands:
      - npx nx affected --target=test --parallel=4 --ci --codeCoverage
      - |
        mkdir -p coverage-reports
        find . -path '*/coverage/coverage-final.json' -exec cp --parents {} coverage-reports/ \;

  post_build:
    commands:
      - aws s3 sync coverage-reports s3://ittal-coverage-reports/$CODEBUILD_BUILD_NUMBER/

Para repos más grandes uso la estrategia de split en el nivel de proyecto con Jest sharding:

// apps/dashboard/project.json
{
  "targets": {
    "test": {
      "executor": "@nx/jest:jest",
      "options": {
        "jestConfig": "apps/dashboard/jest.config.ts",
        "shard": "1/3"
      }
    }
  }
}

Luego en CodeBuild lanzo 3 builds paralelos con variable TEST_SHARD=1/3, 2/3, 3/3.

Benchmark real

gantt
    title Pipeline viejo vs nuevo (branch con cambio en 1 app)
    dateFormat HH:mm:ss
    axisFormat %M:%S

    section Viejo Jenkins
    Install deps       :a1, 00:00:00, 2m
    Build 12 apps      :a2, after a1, 36m
    Test all           :a3, after a2, 15m
    E2E all            :a4, after a3, 10m
    Deploy             :a5, after a4, 3m

    section NX + CodeBuild
    Detect affected    :b1, 00:00:00, 45s
    Build 1 app        :b2, after b1, 3m
    Test affected      :b3, after b1, 2m
    E2E affected       :b4, after b2, 3m
    Deploy             :b5, after b4, 2m

Con cache hit (build idéntico), el pipeline completo tarda 90 segundos porque NX detecta que todo ya está cacheado y solo hace el deploy. Sin cache (primera vez construyendo esa combinación), 8 minutos para un cambio grande.

Tabla comparativa de estrategias

Estrategia	Setup	Cache	Paralelismo	Costo mensual
Jenkins secuencial	Ninguno	No	No	0
NX local sin CI	Ya viene	Local	Sí	0
NX + Nx Cloud	5 min	Remoto	Sí	Desde 16 USD
NX + S3 cache + CodeBuild	1 día	Remoto	Matrix	15-40 USD
GitHub Actions + NX	1 día	Cache Actions	Matrix	Gratis hasta límite

Para este cliente elegí CodeBuild porque ya tenían el resto de su infra en AWS y el role IAM ya existía.

Integración con distribución de tareas

NX Cloud tiene una feature llamada DTE (Distributed Task Execution) que balancea tareas entre agents. Lo repliqué manualmente con SQS:

// ci/distribute-tasks.ts
import { SQSClient, SendMessageBatchCommand } from '@aws-sdk/client-sqs';
import { execSync } from 'child_process';

const sqs = new SQSClient({ region: 'us-east-1' });

async function distributeTasks() {
  const baseSha = execSync('git merge-base HEAD origin/main').toString().trim();
  const affectedJson = execSync(
    `npx nx show projects --affected --base=${baseSha} --json`
  ).toString();
  const affected = JSON.parse(affectedJson) as string[];

  const tasks = affected.flatMap((project) => [
    { project, target: 'build' },
    { project, target: 'test' },
    { project, target: 'lint' },
  ]);

  const batches = [];
  for (let i = 0; i < tasks.length; i += 10) {
    batches.push(tasks.slice(i, i + 10));
  }

  for (const [idx, batch] of batches.entries()) {
    await sqs.send(
      new SendMessageBatchCommand({
        QueueUrl: process.env.TASK_QUEUE_URL!,
        Entries: batch.map((task, i) => ({
          Id: `batch-${idx}-${i}`,
          MessageBody: JSON.stringify(task),
        })),
      })
    );
  }

  console.log(`Enqueued ${tasks.length} tasks for distributed execution`);
}

distributeTasks().catch((err) => {
  console.error(err);
  process.exit(1);
});

Los workers son otras instancias de CodeBuild polleando la queue. Lo usé cuando el monorepo creció a 30 proyectos. Para menos de 15, la matriz estática es más simple.

Lo que aprendí

1. El caché de NX se invalida por cualquier archivo dentro del proyecto.
Descubrí que tenía .DS_Store commiteados de Macs. Cada desarrollador hacía un commit y el caché se invalidaba aunque el código no cambiara. Moraleja: revisa .gitignore cuando configures NX, los archivos espurios matan el caché.

2. dependsOn: ["^build"] es la magia.
El ^ significa "build de las dependencias". Si app1 usa lib-ui, NX construye lib-ui primero automáticamente. Sin esto, los builds fallan intermitentemente por orden.

3. S3 cache hit requiere comparar hashes no archivos.
NX calcula un hash de los inputs (código, config, env vars). El hash es la key en S3. Si tu env var BUILD_ID cambia cada vez, nunca hay cache hit. Exclúyela con runtimeCacheInputs o envInputs.

4. CodeBuild batch tiene límites.
Máximo 20 builds en un batch. Si tu matriz crece, divídela en fases. También el fast-fail por defecto está en false: si una fase falla, las siguientes siguen corriendo. Habilítalo o vas a pagar por builds inútiles.

5. Los artefactos intermedios en S3 necesitan lifecycle.
Cada build subía dist/ de cada app a S3. En un mes tenía 400GB acumulados. Agregué regla de lifecycle: borrar builds antiguos a los 7 días, mover a Glacier los que están en tags de release.

Cuándo NO usar NX

Si tienes un solo proyecto, NX es overkill. El overhead de configurar nx.json, targets, inputs, etc no compensa para un repo con una app.

Si tu equipo no entiende el modelo de grafo de dependencias, NX puede ser confuso. Hay comandos que se comportan diferente según el estado del caché. Para equipos junior, un monorepo simple con npm workspaces es más predecible.

Tampoco NX si tu stack mezcla lenguajes no-JS. NX tiene plugins para Go, Python, Rust, pero son comunitarios y no están al mismo nivel. Para monorepos políglotas, Bazel sigue siendo más robusto aunque más complejo.

El próximo artículo cubre WebSockets con API Gateway para dashboards en tiempo real. Spoiler: migré un cliente de Pusher a AWS native y ahorré 800 USD al mes.