Dónde poner 'use client' en Next.js para no mandar JavaScript de más
Guía/ 13 min de lectura
Qué arrastra la frontera de 'use client' al bundle del navegador, por qué marcar la página entera sale caro y cómo bajarla al componente interactivo, con medición.
- React
- Next.js
- Rendimiento
En este artículo (9)
- Qué es la frontera de cliente que marca 'use client'
- Qué se vuelve código de cliente: el archivo y lo que importa
- Por qué ponerla arriba manda código de más al navegador
- El patrón correcto: bajar la frontera al componente interactivo
- Ejemplo: ficha de producto (servidor vs. cliente)
- Cómo medirlo con el analizador del bundle
- Errores comunes
- Preguntas frecuentes
- Checklist
La directiva 'use client' en Next.js marca una frontera: el archivo que la lleva y todo lo que importa se vuelven código de cliente y viajan al navegador. Por eso no va en la página entera, sino en el componente interactivo más pequeño, como el botón de agregar al carrito. Lo demás se queda en el servidor.
En esta guía vas a ver qué entra en el bundle cuando marcas un archivo, por qué ponerla arriba manda JavaScript de más y cómo bajarla en una ficha de producto, con la medición de una demo local en Next 15.5.23. Si el componente que bajas usa efectos, revisa también cuándo sobra useEffect para datos derivados, y antes de mover código al cliente lee por qué nunca debes poner secretos en NEXT_PUBLIC_.
Qué es la frontera de cliente que marca 'use client'
En el App Router, todo componente es de servidor mientras no digas lo contrario. Las páginas y los layouts se renderizan en el servidor, pueden leer datos cerca de la fuente y usar claves sin exponerlas. Cuando un componente necesita interactividad o APIs del navegador, la guía de Server y Client Components de Next.js te pide marcarlo con "use client".
Según la referencia de React, la directiva va al principio del archivo, antes de cualquier import (los comentarios sí pueden ir antes), con comillas simples o dobles, nunca con backticks. Y lo que marca no es un componente suelto: es una frontera en el árbol de dependencias de módulos, no en el árbol de renderizado. Del lado del servidor queda lo que no la cruza; del lado del cliente, el archivo marcado y todo lo que cuelga de él.
Un detalle que confunde a mucha gente: un Client Component no se renderiza solo en el navegador. Next.js también lo prerenderiza a HTML en el servidor y después manda su JavaScript para hidratarlo, es decir, para conectar los eventos al HTML que ya está en pantalla. Lo que cambia con "use client" es que ese código viaja al navegador y se ejecuta allá.
La guía de Next.js resume cuándo lo necesitas:
| Necesitas 'use client' si el componente usa… | Ejemplo en una tienda |
|---|---|
Estado y manejadores de eventos (useState, onClick, onChange) | Selector de talla, botón de agregar al carrito |
Efectos y ciclo de vida (useEffect) | Un contador que se actualiza solo |
APIs del navegador (localStorage, window, geolocalización) | Recordar el último producto visto |
| Hooks propios que usan lo anterior | Un useCarrito() con estado |
Si un componente solo recibe datos y pinta HTML (título, precio, descripción, reseñas, galería), no lo necesita.
Qué se vuelve código de cliente: el archivo y lo que importa
React lo dice sin rodeos: 'use client' marca el módulo y sus dependencias transitivas como código de cliente. No solo componentes: también helpers, datos y librerías. Todo lo que forma parte de ese subárbol de módulos se manda al navegador y se ejecuta ahí.
La guía de Next.js lo explica igual: una vez que un archivo está marcado, sus imports y los componentes que renderiza directamente entran en el bundle del cliente, así que no hace falta repetir la directiva en cada hijo. Cuando un módulo con 'use client' se importa desde otro módulo de cliente, la directiva no tiene efecto.
Desliza la figura para verla completa
Hay una excepción que es la clave de todo el patrón: los componentes de servidor que pasas como children u otras props no entran en el grafo del cliente. El componente de cliente no los importa; los recibe ya renderizados por el servidor. Por eso, en la figura, Resenas sigue en el servidor aunque se vea dentro de Desplegable.
Por qué ponerla arriba manda código de más al navegador
El caso típico: la ficha de producto tiene un botón con useState, el build falla con «This React Hook only works in a Client Component. To fix, mark the file (or its parent) with the "use client" directive» y la solución rápida es escribir "use client" en la primera línea de page.jsx. Funciona. Pero ahora la página es la raíz del grafo de cliente, y con ella todo lo que importa:
- La librería de validación de los datos (en la demo, zod: 12.8 kB con gzip).
- El módulo de datos completo. En nuestra build, el texto de las reseñas apareció dentro del chunk de JavaScript de la página.
- Los componentes que solo pintan HTML: galería, información del producto, reseñas.
Ese código se descarga, se parsea y se ejecuta para hidratar, aunque el usuario solo vaya a tocar un botón. Además, la página pierde lo que da un Server Component: ya no puede ser un componente async que lea datos en el servidor ni usar claves sin exponerlas. La documentación de Next.js lo deja como consejo explícito: para reducir el JavaScript del cliente, pon 'use client' en los componentes interactivos y no marques partes grandes de la interfaz.
El patrón correcto: bajar la frontera al componente interactivo
- Encuentra lo interactivo. En la ficha, el selector de talla con el botón y el desplegable de reseñas. Nada más usa estado ni eventos.
- Sácalo a su propio archivo con
"use client". Esa es la hoja del árbol. - Deja la página como Server Component. Lee los datos ahí y pasa a la hoja solo lo que necesita, como props serializables: strings, números, arrays y objetos planos. Funciones normales y clases no se pueden pasar desde el servidor.
- Usa
childrenpara meter contenido de servidor en un componente de cliente. Así un acordeón, un modal o un desplegable controla la visibilidad sin arrastrar lo que muestra. - Pon los providers lo más abajo posible. Un provider de contexto es de cliente; según la guía de Next.js, conviene que envuelva
{children}y no todo el documento<html>. - Envuelve los componentes de terceros que usan hooks y no traen la directiva en un archivo tuyo con
'use client', y úsalo desde el servidor.
Ejemplo: ficha de producto (servidor vs. cliente)
La demo es una ficha de tenis con cinco piezas: galería, información, selector de talla con botón, desplegable y reseñas. Los datos salen de lib/producto.js, que los valida con zod. Este es el principio del archivo:
import { z } from "zod";
const Producto = z.object({
nombre: z.string().min(1),
precio: z.number().int().positive(),
tallas: z.array(z.string()).min(1),
imagenes: z.array(z.string()).min(1),
descripcion: z.string(),
resenas: z.array(
z.object({ autor: z.string(), estrellas: z.number().int().min(1).max(5), texto: z.string() }),
),
});
Abajo exporta obtenerProducto(), que devuelve los datos validados, y formatoPrecio(), que formatea centavos con Intl.NumberFormat en pesos mexicanos. Esta es la versión con la frontera arriba, app/arriba/page.jsx:
"use client";
import { obtenerProducto } from "@/lib/producto";
import Galeria from "@/components/Galeria";
import Info from "@/components/Info";
import AgregarAlCarrito from "@/components/AgregarAlCarrito";
import Desplegable from "@/components/Desplegable";
import Resenas from "@/components/Resenas";
export default function Page() {
const producto = obtenerProducto();
return (
<main>
<Galeria imagenes={producto.imagenes} nombre={producto.nombre} />
<Info producto={producto} />
<AgregarAlCarrito tallas={producto.tallas} />
<Desplegable titulo="Reseñas">
<Resenas resenas={producto.resenas} />
</Desplegable>
</main>
);
}
"use client";en la línea 1 conviertepage.jsxen la entrada del grafo de cliente.- Los seis imports pasan con ella al navegador:
obtenerProductocon zod adentro, yGaleria,InfoyResenasaunque no tengan directiva. obtenerProducto()valida con zod en cada render. Con la frontera arriba, esa validación también corre en el navegador al hidratar.- El JSX:
AgregarAlCarritorecibe las tallas yDesplegableenvuelveResenas. AquíResenastambién es de cliente, porquepage.jsxla importa.
Lo interactivo vive en dos archivos que llevan su propia directiva. El botón, components/AgregarAlCarrito.jsx:
"use client";
import { useState } from "react";
export default function AgregarAlCarrito({ tallas }) {
const [talla, setTalla] = useState(tallas[0]);
const [agregado, setAgregado] = useState(false);
return (
<div>
<label>
Talla
<select value={talla} onChange={(e) => setTalla(e.target.value)}>
{tallas.map((t) => (
<option key={t}>{t}</option>
))}
</select>
</label>
<button type="button" onClick={() => setAgregado(true)}>
Agregar al carrito
</button>
{agregado && <p role="status">Talla {talla} agregada</p>}
</div>
);
}
- La directiva es necesaria: el componente usa
useState,onChangeyonClick. - Solo recibe
tallas, un array de strings. Es serializable, así que el servidor se lo puede pasar. - Dos estados: la talla elegida y si ya se agregó. En una tienda real, aquí llamarías a tu acción de carrito.
role="status"hace que un lector de pantalla anuncie el mensaje cuando aparece.
Y el desplegable, components/Desplegable.jsx, que es donde se ve el truco de children:
"use client";
import { useState } from "react";
export default function Desplegable({ titulo, children }) {
const [abierto, setAbierto] = useState(true);
return (
<section>
<button type="button" aria-expanded={abierto} onClick={() => setAbierto(!abierto)}>
{titulo}
</button>
{abierto && children}
</section>
);
}
- El estado
abiertodecide si se muestra el contenido. childrenllega ya renderizado.Desplegableno sabe ni le importa que adentro hay reseñas.aria-expandedle dice a las tecnologías de asistencia si la sección está abierta.
Con esas dos hojas marcadas, la versión con la frontera abajo, app/abajo/page.jsx, es exactamente el mismo archivo sin la primera línea:
-"use client";
-
import { obtenerProducto } from "@/lib/producto";
Ahora la página es un Server Component: valida los datos con zod en el servidor, renderiza galería, información y reseñas a HTML, y solo los dos archivos interactivos viajan como JavaScript. Resenas entra en Desplegable como children, ya renderizada.
Desliza la figura para verla completa
Probamos las dos versiones en el navegador con next start: en ambas, el botón muestra «Talla 25 agregada» y el desplegable oculta y vuelve a mostrar las reseñas. El comportamiento es el mismo; lo que cambia es cuánto código llega.
Cómo medirlo con el analizador del bundle
En Next 15 la medición más rápida ya la tienes: la tabla que imprime next build. La columna First Load JS es el JavaScript que descarga cada ruta en la primera visita (comprobamos que son tamaños con gzip recomprimiendo los archivos de cada ruta). Este es un extracto de la salida de nuestra demo:
Route (app) Size First Load JS
├ ○ /abajo 491 B 103 kB
├ ○ /abajo-fuga 862 B 116 kB
├ ○ /arriba 1.19 kB 117 kB
+ First Load JS shared by all 103 kB
| Ruta | Dónde está 'use client' | First Load JS | ¿zod en el navegador? |
|---|---|---|---|
/arriba | page.jsx | 117 kB | Sí |
/abajo-fuga | AgregarConPrecio.jsx, que importa formatoPrecio | 116 kB | Sí |
/abajo | AgregarAlCarrito.jsx y Desplegable.jsx | 103 kB | No |
Es una medición de laboratorio en mi demo local (Next 15.5.23 con webpack, React 19.0.0, zod 3.25.76), no una promesa para tu tienda. Los 103 kB comunes son React y Next.js, iguales en todas las rutas; la diferencia de 14 kB es casi toda el chunk de zod (56,562 bytes sin comprimir, 12.8 kB con gzip) más los componentes y los datos. En una página real con una librería de fechas, un editor de texto o un resaltador de código, la diferencia crece con lo que importes.
Desliza la figura para verla completa
Para saber qué hay en cada chunk sin instalar nada, busca un texto propio de la librería en la carpeta de salida. En nuestra demo:
grep -rl "ZodError" .next/static/chunks
.next/static/chunks/231-2ddfea1722ade6a5.js
Y cuando necesites el mapa completo, la herramienta oficial para Next 15 es @next/bundle-analyzer, según la guía de package bundling de Next.js 15. Se instala con npm i @next/bundle-analyzer y se activa en next.config.js:
/** @type {import('next').NextConfig} */
const nextConfig = {}
const withBundleAnalyzer = require('@next/bundle-analyzer')({
enabled: process.env.ANALYZE === 'true',
})
module.exports = withBundleAnalyzer(nextConfig)
enableddepende de la variableANALYZE, así que tu build normal no cambia.withBundleAnalyzerenvuelve tu configuración; si ya tienes unnextConfig, pásalo tal cual.- El reporte se genera con
ANALYZE=true npm run build(en PowerShell,$env:ANALYZE="true"; npm run build) y, según la documentación, abre tres pestañas en el navegador.
No lo instalamos en la demo; la configuración es la de la documentación. Tampoco busques otro analizador en Next 15: next --help de la 15.5.23 no tiene ningún comando de análisis. Desde Next 16.1 existe next analyze, integrado con Turbopack, según la guía actual de package bundling. Y si actualizas a Next 16, ten en cuenta que, según la guía de actualización a la versión 16, next build deja de mostrar las columnas Size y First Load JS; ahí mide con next analyze o con Lighthouse.
Errores comunes
- Marcar la página o el layout para que funcione un botón. Funciona, pero manda al navegador todo lo que esa página importa. Saca el botón a su propio archivo.
- Importar un helper desde un módulo pesado. En
/abajo-fuga, el botón importóformatoPreciodesdelib/producto.jspara mostrar el precio. Un solo import: zod y los datos volvieron al navegador (116 kB). Pon los helpers que usa el cliente en un módulo aparte, sin dependencias de servidor. - Importar un componente de servidor dentro de uno de cliente. Al importarlo se vuelve de cliente. Si debe seguir en el servidor, pásalo como
childreno como prop. - Pasar funciones o clases como props desde el servidor. No son serializables y React lanza un error. Pasa datos; la excepción son las Server Functions marcadas con
'use server'. - Poner la directiva después de los imports. Tiene que ser lo primero del archivo; solo los comentarios pueden ir antes.
- Envolver todo el
<html>en un provider. Envuelve solo{children}y ponlo lo más abajo que puedas. - Creer que un componente de cliente nunca corre en el servidor. También se prerenderiza a HTML. Si ahí lees variables de entorno, lee antes qué pasa con NEXT_PUBLIC_ y los secretos.
Preguntas frecuentes
¿'use client' hace que el componente se renderice solo en el navegador?
No. Next.js lo prerenderiza a HTML en el servidor y después manda su JavaScript para hidratarlo. Lo que define la directiva es que el código viaja al navegador y se ejecuta ahí.
¿Tengo que poner 'use client' en cada componente hijo?
No. Todo lo que importa un archivo marcado ya es código de cliente. Ponla en las hojas que se usan desde componentes de servidor, como AgregarAlCarrito.
¿Puedo usar un Server Component dentro de un Client Component?
Sí, pasándolo como children u otra prop desde un componente de servidor. Lo que no puedes es importarlo desde el archivo de cliente, porque entonces se vuelve de cliente.
¿Cómo sé cuánto JavaScript ahorré?
En Next 15, compara la columna First Load JS de next build antes y después, y usa @next/bundle-analyzer para ver qué hay dentro. En Next 16.1 o posterior, usa next analyze.
Checklist
- Ninguna página ni layout lleva
'use client'si no lo necesita entera. - Cada archivo con la directiva usa estado, eventos, efectos o APIs del navegador.
- Los componentes de cliente reciben props serializables, no funciones ni clases.
- El contenido de servidor entra en los componentes de cliente como
children. - Los helpers que usa el cliente no viven en módulos con librerías o datos de servidor.
- Comparaste First Load JS antes y después, y buscaste las librerías pesadas en
.next/static/chunks.
Bajar la frontera es casi siempre borrar una línea y sacar un componente a su archivo. Si al hacerlo encuentras un useEffect que solo calcula datos, sigue con useEffect para datos derivados; si tu página lee variables de entorno, revisa NEXT_PUBLIC_ y secretos en Next.js. Y si buscas el panorama completo de velocidad, está en por qué la velocidad de una tienda suele ser arquitectura y en el botón de agregar al carrito lento.
¿Viste esto en Instagram? Comenta CLIENTE en el Reel y te mando la guía.
Escrito por

Publicado el 30 de octubre de 2026 · actualizado el 1 de noviembre de 2026