Next.js 16 App Router: Production Patterns and Pitfalls

Production-ready Next.js 16 App Router patterns: server components, caching strategies, metadata API, error boundaries, and performance pitfalls to avoid.

E
ECOSIRE Research and Development Team
|19 de marzo de 202612 min de lectura2.7k Palabras|
nextjsapp-routerproductionreact+1

Next.js 16 App Router: patrones de producción y dificultades

Next.js App Router cambió fundamentalmente la forma en que construimos aplicaciones React y, en Next.js 16, los patrones han madurado hasta convertirse en algo genuinamente listo para producción. Pero el cambio conceptual desde Pages Router es pronunciado: los componentes del servidor, la renderización previa parcial, los diseños anidados y un modelo de obtención de datos completamente rediseñado requieren un nuevo cableado del modelo mental que la documentación por sí sola no puede transmitir por completo.

Esta guía cubre los patrones que realmente importan en producción: los que previenen el envenenamiento de la caché, eliminan paquetes de clientes innecesarios y mantienen sus Core Web Vitals verdes a escala. Aprovecharemos la experiencia de crear una aplicación Next.js 16 de 249 páginas con i18n de 11 configuraciones regionales, imágenes OG dinámicas y renderizado del lado del servidor para 5577 archivos de contenido MDX.

Conclusiones clave

  • Nunca use export const metadata en páginas que necesitan SEO con reconocimiento regional; use siempre generateMetadata()
  • Los componentes del servidor son los predeterminados; solo agregue 'use client' cuando realmente necesite interactividad
  • loading.tsx y error.tsx se ubican con su segmento de ruta, no en la raíz
  • El archivo proxy.ts es el middleware de Next.js 16; no cree ambos middleware.ts Y proxy.ts
  • fetch() en Componentes del servidor deduplica automáticamente solicitudes idénticas dentro del mismo procesamiento
  • unstable_cache con etiquetas permite la invalidación del caché quirúrgico sin revalidar todo
  • Se requiere generateStaticParams() para rutas dinámicas que desea generar estáticamente en el momento de la compilación.
  • Los datos estructurados JSON-LD deben desinfectar los desgloses de secuencias de comandos utilizando codificación Unicode

El modelo mental del componente del servidor

El mayor error que cometen los desarrolladores con App Router es utilizar 'use client' demasiado pronto. En Next.js 16, cada componente en el directorio app/ es un componente de servidor de forma predeterminada. Este es el valor predeterminado correcto: los componentes del servidor se procesan en el servidor, no tienen ningún impacto en el paquete de JavaScript y pueden acceder directamente a bases de datos y API.

La regla: empuja 'use client' a las hojas de tu árbol de componentes. Una página puede ser un componente de servidor que recupera datos y los pasa a un shell de componente de cliente ligero que maneja las interacciones.

// app/[locale]/blog/[slug]/page.tsx — Server Component (no directive needed)
import { getBlogPost } from '@/lib/blog';
import { BlogContent } from '@/components/blog/blog-content'; // Client Component

export default async function BlogPostPage({
  params,
}: {
  params: Promise<{ slug: string; locale: string }>;
}) {
  const { slug, locale } = await params;
  const post = await getBlogPost(slug, locale);

  if (!post) notFound();

  return (
    <article>
      <h1>{post.title}</h1>
      {/* Server Component — no JS sent to browser */}
      <PostMeta author={post.author} date={post.date} />
      {/* Client Component — only this file sent as JS */}
      <BlogContent content={post.content} />
    </article>
  );
}

// components/blog/blog-content.tsx — Client Component
'use client';

import { useState } from 'react';

export function BlogContent({ content }: { content: string }) {
  const [expanded, setExpanded] = useState(false);

  return (
    <div>
      <div>{content}</div>
      {/* Client-side interactivity lives here */}
    </div>
  );
}

La idea clave: BlogContent envía JavaScript al navegador. PostMeta no lo hace. Cada directiva 'use client' innecesaria infla su paquete.

generarMetadatos sobre metadatos estáticos

El export const metadata estático es tentador por su simplicidad, pero no puede tener en cuenta la configuración regional, no puede acceder a los parámetros de ruta y no puede recuperar datos. Para cualquier aplicación real, generateMetadata() es la única opción correcta:

// app/[locale]/blog/[slug]/page.tsx
import type { Metadata } from 'next';
import { getTranslations } from 'next-intl/server';

export async function generateMetadata({
  params,
}: {
  params: Promise<{ slug: string; locale: string }>;
}): Promise<Metadata> {
  const { slug, locale } = await params;
  const post = await getBlogPost(slug, locale);

  if (!post) return {};

  const locales = ['en', 'zh', 'es', 'ar', 'pt', 'fr', 'de', 'ja', 'tr', 'hi', 'ur'];

  return {
    title: post.title,
    description: post.description,
    alternates: {
      canonical: `https://ecosire.com/${locale === 'en' ? '' : locale + '/'}blog/${slug}`,
      languages: Object.fromEntries(
        locales.map((loc) => [
          loc,
          `https://ecosire.com/${loc === 'en' ? '' : loc + '/'}blog/${slug}`,
        ])
      ),
    },
    openGraph: {
      title: post.title,
      description: post.description,
      images: [`/api/og/blog/${slug}?locale=${locale}`],
      type: 'article',
      publishedTime: post.date,
    },
  };
}

El campo alternates.languages genera etiquetas hreflang para cada ubicación, algo esencial para el SEO multilingüe. Los motores de búsqueda los utilizan para ofrecer la versión de idioma correcta a cada usuario.

Diseños anidados y estado compartido

El sistema de diseño anidado de App Router es poderoso pero tiene una restricción no obvia: los diseños no pueden pasar datos a sus hijos a través de accesorios. La solución alternativa es React Context (solo componentes del cliente) o recuperar datos de forma independiente en cada nivel.

app/
  [locale]/
    layout.tsx          <- Locale layout: fonts, i18n provider, theme
    page.tsx            <- Homepage
    blog/
      layout.tsx        <- Blog layout: sidebar, breadcrumbs
      page.tsx          <- Blog list
      [slug]/
        layout.tsx      <- Post layout: reading progress, TOC
        page.tsx        <- Post content
        loading.tsx     <- Skeleton while post loads
        error.tsx       <- Error boundary for this segment

Cada layout.tsx envuelve a sus hijos de forma independiente. Los datos recuperados en un diseño principal no están disponibles automáticamente para los secundarios: cada componente que necesita datos los recupera de forma independiente. Next.js 16 deduplica llamadas fetch() idénticas dentro de un ciclo de renderizado, por lo que esto no es tan costoso como parece.

// app/[locale]/layout.tsx
import { NextIntlClientProvider } from 'next-intl';
import { getMessages } from 'next-intl/server';

export default async function LocaleLayout({
  children,
  params,
}: {
  children: React.ReactNode;
  params: Promise<{ locale: string }>;
}) {
  const { locale } = await params;
  const messages = await getMessages();

  return (
    <html lang={locale} dir={['ar', 'ur'].includes(locale) ? 'rtl' : 'ltr'}>
      <body>
        <NextIntlClientProvider messages={messages}>
          {children}
        </NextIntlClientProvider>
      </body>
    </html>
  );
}

Estrategia de almacenamiento en caché: las cuatro capas

Next.js 16 tiene cuatro capas de almacenamiento en caché distintas. Es necesario comprender los cuatro para razonar por qué una página se actualiza o no:

1. Solicitar memorización: la misma URL fetch() dentro de un ciclo de renderizado se llama una vez. Automático, sin configuración.

2. Caché de datos: persistente en todas las solicitudes. Las respuestas fetch() se almacenan en caché indefinidamente de forma predeterminada.

// Force revalidation every hour
const data = await fetch('/api/posts', { next: { revalidate: 3600 } });

// Never cache (equivalent to SSR)
const data = await fetch('/api/posts', { cache: 'no-store' });

3. Caché de ruta completa: carga útil HTML estática y RSC almacenada en caché en el momento de la compilación para rutas estáticas.

4. Caché del enrutador: caché del lado del cliente de las rutas visitadas. Persiste durante la sesión del navegador.

Para consultas de bases de datos (sin recuperación), utilice unstable_cache:

import { unstable_cache } from 'next/cache';

const getCachedBlogPosts = unstable_cache(
  async (locale: string) => {
    return db.select().from(posts).where(eq(posts.locale, locale));
  },
  ['blog-posts'], // Cache key
  {
    revalidate: 3600, // Revalidate hourly
    tags: ['blog'], // Tag for manual invalidation
  }
);

// Invalidate from a Server Action or Route Handler:
import { revalidateTag } from 'next/cache';
revalidateTag('blog'); // All blog-tagged caches cleared

Límites de error: se requieren dos niveles

Las aplicaciones de producción necesitan dos límites de error: uno para páginas con reconocimiento regional y otro global para errores de nivel raíz.

// app/[locale]/error.tsx — Locale-level error boundary
'use client';

import { useTranslations } from 'next-intl';
import { useEffect } from 'react';

export default function LocaleError({
  error,
  reset,
}: {
  error: Error & { digest?: string };
  reset: () => void;
}) {
  const t = useTranslations('errors');

  useEffect(() => {
    // Log to error tracking service
    console.error(error);
  }, [error]);

  return (
    <div className="flex flex-col items-center justify-center min-h-screen">
      <h2>{t('title')}</h2>
      <p>{t('description')}</p>
      <button onClick={reset}>{t('retry')}</button>
    </div>
  );
}

// app/global-error.tsx — Root fallback (no i18n available here)
'use client';

export default function GlobalError({
  error,
  reset,
}: {
  error: Error & { digest?: string };
  reset: () => void;
}) {
  // Cannot use useTranslations here — no NextIntlClientProvider above
  // Use inline styles — no Tailwind in root error boundaries
  return (
    <html>
      <body>
        <div style={{ display: 'flex', flexDirection: 'column', alignItems: 'center', padding: '2rem' }}>
          <h2 style={{ fontSize: '1.5rem', fontWeight: 'bold' }}>Something went wrong</h2>
          <button
            onClick={reset}
            style={{ marginTop: '1rem', padding: '0.5rem 1rem', cursor: 'pointer' }}
          >
            Try again
          </button>
        </div>
      </body>
    </html>
  );
}

El global-error.tsx reemplaza la raíz layout.tsx cuando se activa, por lo que debe incluir las etiquetas <html> y <body>. No puede acceder a los proveedores de contexto que se encuentran en el diseño: ni i18n, ni tema, ni contexto de autenticación.

Middleware: proxy.ts frente a middleware.ts

Next.js usa middleware.ts (o middleware.js) para el middleware perimetral. En un proyecto que utiliza next-intl v4, la configuración del middleware a menudo cambia de nombre a proxy.ts y se reexporta, lo que crea un error crítico: no cree ambos middleware.ts y proxy.ts. Tener ambos provoca un error de compilación.

El patrón correcto para combinar i18n con protección de autenticación:

// src/proxy.ts — This IS the Next.js middleware
import createMiddleware from 'next-intl/middleware';
import { NextRequest, NextResponse } from 'next/server';
import { routing } from './i18n/routing';

const intlMiddleware = createMiddleware(routing);

const protectedPaths = ['/dashboard', '/portal'];

export default function middleware(request: NextRequest) {
  const { pathname } = request.nextUrl;

  // Check auth for protected paths
  const isProtected = protectedPaths.some((path) =>
    pathname.includes(path)
  );

  if (isProtected) {
    const token = request.cookies.get('ecosire_auth');
    if (!token) {
      const url = request.nextUrl.clone();
      url.pathname = '/auth/login';
      // Prevent open redirect — never allow // prefix
      const redirect = pathname.startsWith('//') ? '/' : pathname;
      url.searchParams.set('redirect', redirect);
      return NextResponse.redirect(url);
    }
  }

  return intlMiddleware(request);
}

export const config = {
  matcher: ['/((?!api|_next/static|_next/image|favicon.ico|.*\\..*).*)'],
};

Este único archivo maneja tanto la detección local de i18n como la protección de autenticación. El config.matcher excluye archivos estáticos, rutas API y componentes internos de Next.js.

Seguridad de datos estructurados JSON-LD

Los scripts JSON-LD son un vector XSS común. Si sus datos contienen una etiqueta de secuencia de comandos de cierre, pueden salirse del bloque de secuencia de comandos. La solución es obligatoria: codifique el carácter menor que:

// components/seo/JsonLd.tsx
interface JsonLdProps {
  data: Record<string, unknown>;
}

export function JsonLd({ data }: JsonLdProps) {
  // Sanitize script tag breakout attempts by encoding '<' as unicode
  const json = JSON.stringify(data).replace(/</g, '\\u003c');

  return (
    <script
      type="application/ld+json"
      // Safe: content is JSON-serialized and sanitized above
      suppressHydrationWarning
      ref={(el) => { if (el) el.textContent = json; }}
    />
  );
}

Uso en una página:

<JsonLd
  data={{
    '@context': 'https://schema.org',
    '@type': 'BlogPosting',
    headline: post.title,
    description: post.description,
    inLanguage: locale,
    author: {
      '@type': 'Organization',
      name: 'ECOSIRE',
    },
  }}
/>

El campo inLanguage es esencial para el SEO multilingüe: indica a los rastreadores de IA y a los motores de búsqueda en qué idioma se encuentra el contenido, lo que mejora la precisión de la clasificación para consultas que no están en inglés.

Imágenes dinámicas OG

La API ImageResponse de Next.js 16 genera imágenes OG por página en el borde. La configuración para publicaciones de blog:

// app/api/og/blog/[slug]/route.tsx
import { ImageResponse } from 'next/og';

export const runtime = 'edge';

export async function GET(
  request: Request,
  { params }: { params: Promise<{ slug: string }> }
) {
  const { slug } = await params;
  const post = await getPostMeta(slug);

  return new ImageResponse(
    (
      <div
        style={{
          display: 'flex',
          flexDirection: 'column',
          justifyContent: 'flex-end',
          width: '100%',
          height: '100%',
          background: 'linear-gradient(135deg, #0a0a0a 0%, #1a1a2e 100%)',
          padding: '60px',
        }}
      >
        <div style={{ fontSize: 48, fontWeight: 700, color: 'white', lineHeight: 1.2 }}>
          {post.title}
        </div>
        <div style={{ fontSize: 24, color: '#94a3b8', marginTop: 20 }}>
          {post.description}
        </div>
      </div>
    ),
    { width: 1200, height: 630 }
  );
}

Errores y soluciones comunes

Error 1: Obtener datos en los componentes del cliente cuando los componentes del servidor funcionarían

Si un componente solo muestra datos y no necesita el estado de React ni las API del navegador, debería ser un componente de servidor. Agregar 'use client' fuerza todo lo que importa al paquete del cliente.

Error 2: Faltan límites de suspenso en torno a los componentes del servidor asíncronos

// Without Suspense — entire page blocks until data loads
export default async function Page() {
  const data = await slowFetch(); // 2 seconds
  return <div>{data}</div>;
}

// With Suspense — page streams, slow part shows skeleton
export default function Page() {
  return (
    <Suspense fallback={<DataSkeleton />}>
      <SlowDataComponent />
    </Suspense>
  );
}

Error 3: usar cookies() o encabezados() en funciones almacenadas en caché

cookies() y headers() son API dinámicas que optan por la ruta hacia la representación dinámica. Usarlos dentro de una devolución de llamada unstable_cache rompe silenciosamente el caché.

Error 4: Olvidarse de esperar los parámetros en Next.js 16

En Next.js 16, params ahora es una Promesa. Olvidar await provoca errores de tiempo de ejecución:

// Next.js 15 — params was synchronous
export default function Page({ params }: { params: { slug: string } }) {
  const { slug } = params;
}

// Next.js 16 — params is async
export default async function Page({
  params,
}: {
  params: Promise<{ slug: string }>;
}) {
  const { slug } = await params; // Required
}

Preguntas frecuentes

¿Cuándo debo usar generateStaticParams() frente al renderizado dinámico?

Utilice generateStaticParams() para contenido que cambia con poca frecuencia (publicaciones de blog, páginas de productos, documentación). Esto genera HTML estático en el momento de la compilación sin costo de tiempo de ejecución. Utilice la representación dinámica para contenido personalizado, datos en tiempo real o páginas con miles de variantes donde el tiempo de compilación sería prohibitivo. Combine ambos con ISR (revalidate) para contenido que cambia ocasionalmente.

¿Cómo manejo la autenticación en App Router?

Almacene tokens de autenticación en cookies HttpOnly, nunca localStorage o sessionStorage. Utilice middleware (proxy.ts) para comprobar la presencia de cookies en rutas protegidas. En Componentes del servidor, lea las cookies con cookies() de next/headers. Pase datos de usuario del servidor al cliente a través de accesorios o React Context, nunca volviendo a leer la cookie en los Componentes del Cliente.

¿Cuál es la diferencia entre load.tsx y Suspense?

loading.tsx es un archivo especial que Next.js ajusta automáticamente en un límite de suspenso para todo el segmento de ruta. Se muestra inmediatamente mientras se carga el contenido asíncrono del segmento. Los límites manuales Suspense le brindan un control más preciso: puede mostrar diferentes esqueletos para diferentes partes de una página. Ambos utilizan el mismo mecanismo subyacente de React Suspense.

¿Cómo comparto el estado entre los componentes del servidor y del cliente?

No es posible: los componentes del servidor se procesan una vez y no tienen estado de tiempo de ejecución. Pasar datos del servidor al cliente mediante accesorios. Para el estado del lado del cliente que debe persistir en todas las navegaciones, utilice parámetros de búsqueda de URL (para el estado que se puede compartir), Zustand o Redux (para el estado efímero) o cookies (para las preferencias del usuario). Nunca intente importar el estado de un componente de cliente a un componente de servidor.

¿Cómo configuro Turbopack para el desarrollo?

Agregue --turbo a su script de desarrollo: "dev": "next dev --turbo". Turbopack es el paquete basado en Rust de Next.js 16 con arranques en frío y HMR significativamente más rápidos. Está listo para producción para la mayoría de los proyectos, pero tiene algunas incompatibilidades con el complemento del paquete web. Verifique sus dependencias específicas con la lista de compatibilidad de Turbopack antes de cambiar.

Próximos pasos

Crear una aplicación de producción Next.js 16 que maneje 11 configuraciones regionales, miles de páginas y requisitos de rendimiento de nivel empresarial es una tarea de ingeniería importante. El equipo de frontend de ECOSIRE ha enviado exactamente esto: una plataforma Next.js 16 de 249 páginas con SEO multilingüe, imágenes OG dinámicas y tiempos de respuesta inferiores a un segundo.

Si está ampliando su aplicación Next.js o necesita soporte de ingeniería de interfaz empresarial, explore nuestros servicios de desarrollo para ver cómo podemos ayudarlo.

Etiquetas:nextjsapp-routerproductionreactfrontend
Compartir:
E

Escrito por

ECOSIRE Research and Development Team

Construyendo productos digitales de nivel empresarial en ECOSIRE. Compartiendo perspectivas sobre integraciones Odoo, automatización de eCommerce y soluciones empresariales impulsadas por IA.

Ver todas las publicaciones

Artículos relacionados

i18n

Internationalization in Next.js: 11-Locale Implementation

Build a production-ready 11-locale Next.js app with next-intl v4. Covers routing, RTL support, translation workflows, hreflang SEO, and server/client component patterns.

10 min de lectura
nginx

Nginx Production Configuration: SSL, Caching, and Security

Nginx production configuration guide: SSL termination, HTTP/2, caching headers, security headers, rate limiting, reverse proxy setup, and Cloudflare integration patterns.

8 min de lectura
openclaw

Testing and Monitoring AI Agents in Production

A complete guide to testing and monitoring AI agents in production environments. Covers evaluation frameworks, observability, drift detection, and incident response for OpenClaw deployments.

14 min de lectura
Volver a todos los artículos
Chatea en whatsapp