Next.js

Las carpetas bajo app/ representan segmentos de URL; page.tsx define una página y layout.tsx una interfaz compartida que envuelve las páginas descendientes. Un segmento como [slug] habilita rutas dinámicas. Los layouts persisten entre navegaciones y pueden conservar estado, así que ubica en ellos solo lo que realmente deba compartirse. Link facilita la navegación cliente y el precargado de rutas. Layouts and Pages

Un segmento dinámico como [slug] entrega sus parámetros a la página; el parámetro searchParams representa la consulta de la URL. En versiones actuales de Next.js, params y searchParams son promesas en componentes de servidor y se leen con await; useParams y useSearchParams sirven desde el cliente. Elige la API según si el dato carga contenido en el servidor o solo filtra estado que ya está en el navegador. Dynamic Segments y Layouts and Pages

Un layout.tsx envuelve rutas hijas y normalmente conserva estado entre navegaciones; template.tsx crea una nueva instancia al navegar por su segmento, por lo que reinicia estado local y vuelve a ejecutar efectos. Un route group como (marketing) organiza archivos sin añadir ese nombre a la URL, y puede separar diseños. Si navegás entre distintos root layouts, se produce una carga completa de página. Layouts and Templates y Route Groups

Parallel Routes, declaradas con slots @nombre, permiten mostrar varias subrutas dentro de un layout, por ejemplo paneles independientes de un dashboard. Intercepting Routes permiten abrir una ruta dentro del contexto actual —como una foto en un modal— mientras la misma URL puede abrir una página completa al refrescar o llegar mediante enlace directo. Son herramientas para flujos con varias regiones o navegación contextual; requieren definir estados de respaldo y navegación directa. Parallel Routes e Intercepting Routes

En App Router, los componentes son de servidor de forma predeterminada: pueden leer datos cerca del origen y mantener secretos en el servidor, y su JavaScript de componente no se envía al navegador. Usa componentes de cliente con 'use client' cuando necesites estado interactivo, manejadores de eventos, hooks de ciclo de vida o APIs del navegador. Esa directiva establece una frontera del grafo de módulos; sus importaciones también pueden formar parte del paquete cliente. Server and Client Components

En el servidor, Next.js produce un payload de React Server Components con el resultado de los Server Components, referencias a los Client Components y las props que cruzan esa frontera. En la carga inicial también genera HTML, que el navegador puede mostrar antes de que la página sea interactiva; React hidrata los Client Components adjuntando sus manejadores. El payload y las props no son un lugar para enviar secretos: cualquier dato serializado al cliente puede ser inspeccionado por quien recibe la página. Server and Client Components

Una página puede prerenderizar contenido durante el build o resolver partes que dependen de datos de la solicitud. Renderizado y caché son conceptos relacionados pero distintos: una página dinámica puede reutilizar algunos datos cacheados, y una página prerenderizada puede tener secciones dinámicas. La lectura de cookies, headers o parámetros de búsqueda puede requerir datos de la solicitud. No asumas que la ruta entera comparte el mismo comportamiento; verifica las reglas de la versión y la configuración del proyecto. Rendering y Dynamic APIs

El streaming permite enviar partes de una ruta a medida que están listas, en lugar de esperar a que todos los datos terminen. loading.tsx crea una interfaz de carga para el segmento y funciona como límite de Suspense; un límite con el componente Suspense más cercano a una operación lenta permite mostrar el resto de la página sin bloquearla. Diseña el fallback como una representación útil de lo que está cargando, y coloca el límite alrededor de la sección que realmente puede esperar. Data Fetching and Streaming y loading.js

Un Server Component puede usar fetch, un ORM o un cliente de base de datos en una función asíncrona. Cuando dos solicitudes no dependen entre sí, inícialas en paralelo en vez de esperar una y luego la otra; para evitar repetir una lectura dentro de un render, usa las herramientas de memoización adecuadas para el tipo de acceso. Mantené los secretos y las credenciales de base de datos en módulos exclusivos del servidor. Fetching Data y Data Security

Decidí qué puede compartirse y durante cuánto tiempo antes de cachear una lectura. La API y los valores predeterminados de fetch, la caché de renderizado y la revalidación han cambiado entre versiones; declararlos y comprobarlos evita depender de una suposición. Datos personalizados por usuario no deben quedar en una caché compartida sin que la clave y las reglas de aislamiento lo contemplen. Caching y production checklist

En Next.js 16, Cache Components se habilita con cacheComponents en la configuración; entonces use cache marca una ruta, componente o función como cacheable, y cacheLife define su duración. cacheTag permite invalidar por etiqueta. El modelo anterior usa opciones de segmento y APIs que difieren, así que no mezcles ejemplos de ambos modelos sin verificar si la bandera está habilitada y qué versión está fijada. Datos dependientes de cookies u otros valores por solicitud no deben entrar accidentalmente en una salida compartida. Cache Components, use cache y cacheComponents

Con Cache Components, cacheTag asocia una etiqueta a una lectura cacheada; luego updateTag puede invalidarla desde una Server Action y revalidateTag permite revalidar con semántica stale-while-revalidate. revalidatePath invalida datos asociados a una ruta. Elige según si la persona necesita ver inmediatamente el dato nuevo o puede tolerar contenido anterior mientras se actualiza; las APIs disponibles y su comportamiento dependen del modelo de caché y la versión. Revalidating

Link amplía el elemento ancla con transición cliente y prefetching según la ruta y configuración. Los layouts compartidos pueden permanecer montados; las rutas dinámicas pueden mostrar la interfaz de carga mientras el servidor las resuelve. Usa useRouter para navegación imperativa desde un Client Component cuando el flujo lo requiera, y preferí enlaces declarativos para navegación normal y accesible. Linking and Navigating y useRouter

El estado de una interacción temporal, como un menú abierto, pertenece al Client Component que la controla. El estado que debe compartirse o sobrevivir a una recarga suele corresponder a la URL, al servidor o a almacenamiento persistente, según el caso. Usa parámetros de búsqueda para filtros o paginación que deban poder enlazarse; no conviertas cada dato en estado global ni guardes en el cliente información que debe permanecer privada. React state y Next.js search params

Una Server Action es una función asíncrona que se ejecuta en el servidor y puede invocarse desde una interfaz cliente o un formulario. Puede validar los datos, realizar una mutación y revalidar la interfaz o los datos asociados. La validación del navegador mejora la experiencia, pero no reemplaza validar en el servidor; tratá cada Action como una entrada que puede recibir solicitudes no confiables. Mutating Data y Data Security

Un Route Handler (route.ts) expone un endpoint HTTP para métodos como GET o POST, útil para una API consumida por otros clientes, webhooks o integraciones. Una Server Action conviene para mutaciones ligadas a una interacción de la app y su actualización de interfaz. No es necesario construir un endpoint para cada lectura interna: un Server Component puede llamar directamente a la capa de datos. En ambos casos, autenticá, autorizá y validá la entrada en el servidor. Route Handlers y Mutating Data

loading.tsx muestra un fallback durante la espera; error.tsx define un límite de error para el segmento y debe ser un Client Component; not-found.tsx representa el caso de recurso inexistente, que puede activarse con notFound(). Diferenciá errores esperados —como una validación rechazada— de fallos inesperados, y evita filtrar stack traces o datos sensibles al usuario. Agregá una opción clara para reintentar o volver cuando sea posible. Error Handling y notFound

Las pruebas unitarias cubren funciones y lógica aislada; las de componente revisan interacciones en una unidad de UI; las E2E ejercitan recorridos reales en un navegador y servidor. Next.js documenta Jest, Vitest, Playwright y Cypress, cada cual con usos distintos. Para componentes de servidor asíncronos, la documentación advierte que algunas herramientas no tienen soporte completo y recomienda E2E para cubrir el comportamiento integrado. Testing y Vitest

Autenticación comprueba quién es la persona; gestión de sesión mantiene ese estado entre solicitudes; autorización decide qué recurso o acción puede usar. Ocultar un enlace o redirigir en una capa superficial no protege datos: verificá permisos también cerca del acceso a datos y en cada acción que modifica información. Para una app nueva, Next.js recomienda una capa de acceso a datos que centralice autorización y retorne solo los campos permitidos. Authentication y Data Security

Tratá cada Server Action y Route Handler como un punto de entrada público: autenticá, autorizá la operación y validá cada dato en el servidor. Una capa de acceso a datos centraliza esos controles y devuelve DTOs mínimos para no exponer secretos o campos privados. Mantén claves en variables del servidor; solo valores intencionalmente públicos deben llevar el prefijo NEXT_PUBLIC_. Las acciones cifradas o IDs difíciles de adivinar no sustituyen autorización. Data Security y Authentication

No insertes HTML no confiable sin sanitizarlo; React escapa texto por defecto, pero funciones de HTML sin procesar eliminan esa protección. Una Content Security Policy (CSP) limita los orígenes permitidos para scripts, estilos y otros recursos, y puede reducir el impacto de ciertas inyecciones. Además, evita cachear datos privados entre usuarios y no serialices secretos desde Server Components hacia Client Components. Content Security Policy y Data Security

Dejá como Server Components las partes que no requieren interacción de navegador, y marcá con 'use client' el límite interactivo más pequeño posible. Cada importación que cuelga de esa frontera puede aumentar el paquete cliente. Mantén providers cliente lo más profundos que sea práctico y carga componentes o bibliotecas grandes bajo demanda si el análisis del bundle muestra que conviene. Server and Client Components y production checklist

next/image puede optimizar imágenes y reservar su espacio para reducir cambios de layout; next/font puede servir fuentes junto con los assets de la app, y next/script controla la carga de scripts de terceros. No son sustitutos de medición: verificá tamaño, formatos, prioridad y efecto en Core Web Vitals. Analizá bundles y medí una build de producción, ya que el comportamiento de desarrollo no refleja completamente el de usuarios reales. Production checklist, Image Optimization y Font Optimization

Primero reproduce el problema con una build de producción; las rutas y cachés se comportan de manera distinta durante desarrollo. Un error de hidratación indica que el HTML inicial y el primer render del cliente no coinciden, a menudo por usar hora, aleatoriedad, APIs del navegador o datos mutables durante el render inicial. Inspeccioná el mensaje y el segmento afectado, y mueve el acceso al navegador a un componente cliente después de la hidratación cuando corresponda. React hydration y Next.js production checklist

next build genera una build de producción y detecta errores de compilación que pueden no verse en el servidor de desarrollo. Ejecuta también pruebas y verificaciones de tipos en CI; mantén las variables secretas fuera del repositorio y recuerda que NEXT_PUBLIC_ las expone al cliente en el build. Luego ejecuta next start para probar el artefacto en un entorno parecido a producción. Production checklist y Environment Variables

Elige un runtime que soporte las funciones usadas: Server Actions, renderizado de servidor, streaming, revalidación y caché no están disponibles en cualquier hosting estático. La documentación actual describe el servidor Node.js y Docker, y recomienda un reverse proxy al autoalojar. En varias instancias, coordiná el caché y sus invalidaciones; durante despliegues progresivos, considerá desajustes de versión entre cliente y servidor. Self-Hosting y Deploying to Platforms

Primero confirmaría si la respuesta provino de una caché compartida y qué datos forman su clave; los datos privados deben aislarse por usuario o no cachearse compartidamente. Centralizaría autorización y lectura en la capa de datos, devolvería un DTO mínimo y probaría acceso como distintos usuarios. Después definiría el nivel de frescura necesario y la invalidación tras cada mutación, y reproduciría el caso en una build de producción con logs que no revelen información sensible. Data Security y Revalidating

Versiones: Las páginas consultadas corresponden al App Router actual de Next.js. En versiones actuales, params y searchParams de páginas son asíncronos; código anterior puede usar firmas distintas. Cache Components se incorporó en Next.js 16 mediante la opción cacheComponents y cambia el modelo de caché; las reglas de fetch, revalidación y APIs disponibles dependen de la versión y de esa configuración. Dynamic Segments, Cache Components y migrating to Cache Components