|
| 1 | +--- |
| 2 | +source-updated-at: 2025-05-29T18:05:49.000Z |
| 3 | +translation-updated-at: 2025-06-02T19:19:19.902Z |
| 4 | +title: Almacenamiento en caché componible con Next.js |
| 5 | +description: Conozca más sobre el diseño de la API y los beneficios de 'use cache' |
| 6 | +author: |
| 7 | + - name: Lee Robinson |
| 8 | + image: /static/team/lee.jpg |
| 9 | +date: 2025-01-03T14:00:00.507Z |
| 10 | +image: >- |
| 11 | + https://h8DxKfmAPhn8O0p3.public.blob.vercel-storage.com/static/blog/composable-caching/twitter-card.png |
| 12 | +--- |
| 13 | + |
| 14 | +Estamos trabajando en un modelo de almacenamiento en caché simple y potente para Next.js. En una publicación anterior, hablamos sobre [nuestra experiencia con el caché](/blog/our-journey-with-caching) y cómo llegamos a la directiva `'use cache'`. |
| 15 | + |
| 16 | +Esta publicación discutirá el diseño de la API y los beneficios de `'use cache'`. |
| 17 | + |
| 18 | +[¿Qué es `'use cache'`?](#what-is-use-cache) |
| 19 | +-------------------------------------------- |
| 20 | + |
| 21 | +`'use cache'` hace que tu aplicación sea más rápida almacenando en caché datos o componentes según sea necesario. |
| 22 | + |
| 23 | +Es una "directiva" de JavaScript —un literal de cadena que agregas en tu código— que le indica al compilador de Next.js que entre en un "límite" diferente. Por ejemplo, pasar del servidor al cliente. |
| 24 | + |
| 25 | +Esta es una idea similar a las directivas de React como `'use client'` y `'use server'`. Las directivas son instrucciones del compilador que definen dónde debe ejecutarse el código, permitiendo que el framework optimice y orqueste piezas individuales por ti. |
| 26 | + |
| 27 | +[¿Cómo funciona?](#how-does-it-work) |
| 28 | +-------------------------------------- |
| 29 | + |
| 30 | +Comencemos con un ejemplo simple: |
| 31 | + |
| 32 | +``` |
| 33 | +async function getUser(id) { |
| 34 | + 'use cache'; |
| 35 | + let res = await fetch(`https://api.vercel.app/user/${id}`); |
| 36 | + return res.json(); |
| 37 | +} |
| 38 | +``` |
| 39 | + |
| 40 | +Detrás de escenas, Next.js transforma este código en una función del servidor debido a la directiva `'use cache'`. Durante la compilación, se encuentran las "dependencias" de esta entrada de caché y se usan como parte de la clave de caché. |
| 41 | + |
| 42 | +Por ejemplo, `id` se convierte en parte de la clave de caché. Si llamamos a `getUser(1)` múltiples veces, devolvemos la salida memorizada de la función del servidor en caché. Cambiar este valor creará una nueva entrada en el caché. |
| 43 | + |
| 44 | +Veamos un ejemplo usando la función en caché en un componente del servidor con un [cierre](https://v0.dev/chat/5kD47RIecQK?b=b_rCP4CvfbFFW). |
| 45 | + |
| 46 | +``` |
| 47 | +function Profile({ id }) { |
| 48 | + async function getNotifications(index, limit) { |
| 49 | + 'use cache'; |
| 50 | + return await db |
| 51 | + .select() |
| 52 | + .from(notifications) |
| 53 | + .limit(limit) |
| 54 | + .offset(index) |
| 55 | + .where(eq(notifications.userId, id)); |
| 56 | + } |
| 57 | + |
| 58 | + return <User notifications={getNotifications} />; |
| 59 | +} |
| 60 | +``` |
| 61 | + |
| 62 | +Este ejemplo es más difícil. ¿Puedes identificar todas las dependencias que deben ser parte de la clave de caché? |
| 63 | + |
| 64 | +Los argumentos `index` y `limit` tienen sentido —si estos valores cambian, seleccionamos un segmento diferente de las notificaciones. Sin embargo, ¿qué pasa con el `id` del usuario? Su valor proviene del componente padre. |
| 65 | + |
| 66 | +El compilador puede entender que `getNotifications` también depende de `id`, y su valor se incluye automáticamente en la clave de caché. Esto evita toda una categoría de problemas de caché por dependencias incorrectas o faltantes en la clave de caché. |
| 67 | + |
| 68 | +[¿Por qué no usar una función de caché?](#why-not-use-a-cache-function) |
| 69 | +-------------------------------------------------------------- |
| 70 | + |
| 71 | +Revisemos el último ejemplo. ¿Podríamos usar una función `cache()` en lugar de una directiva? |
| 72 | + |
| 73 | +``` |
| 74 | +function Profile({ id }) { |
| 75 | + async function getNotifications(index, limit) { |
| 76 | + return await cache(async () => { |
| 77 | + return await db |
| 78 | + .select() |
| 79 | + .from(notifications) |
| 80 | + .limit(limit) |
| 81 | + .offset(index) |
| 82 | + // ¡Ups! ¿Dónde incluimos id en la clave de caché? |
| 83 | + .where(eq(notifications.userId, id)); |
| 84 | + }); |
| 85 | + } |
| 86 | + |
| 87 | + return <User notifications={getNotifications} />; |
| 88 | +} |
| 89 | +``` |
| 90 | + |
| 91 | +Una función `cache()` no podría mirar dentro del cierre y ver que el valor de `id` debería ser parte de la clave de caché. Tendrías que especificar manualmente que `id` es parte de tu clave. Si olvidas hacerlo o lo haces incorrectamente, arriesgas colisiones de caché o datos obsoletos. |
| 92 | + |
| 93 | +Los cierres pueden capturar todo tipo de variables locales. Un enfoque ingenuo podría accidentalmente incluir (u omitir) variables que no pretendías. Eso puede llevar a almacenar en caché los datos incorrectos, o podría arriesgar la contaminación del caché si información sensible se filtra en la clave de caché. |
| 94 | + |
| 95 | +`'use cache'` le da al compilador suficiente contexto para manejar cierres de manera segura y producir claves de caché correctamente. Una solución solo en tiempo de ejecución, como `cache()`, requeriría que hicieras todo manualmente —y es fácil cometer errores. En contraste, una directiva puede analizarse estáticamente para manejar de manera confiable todas tus dependencias bajo el capó. |
| 96 | + |
| 97 | +[¿Cómo se manejan los valores de entrada no serializables?](#how-are-non-serialized-input-values-handled) |
| 98 | +-------------------------------------------------------------------------------------------- |
| 99 | + |
| 100 | +Tenemos dos tipos diferentes de valores de entrada para almacenar en caché: |
| 101 | + |
| 102 | +* **Serializables**: Aquí, "serializable" significa que una entrada puede convertirse en un formato estable basado en cadenas _sin_ perder significado. Mientras que muchas personas piensan primero en `JSON.stringify`, en realidad usamos la serialización de React (por ejemplo, a través de Componentes del Servidor) para manejar un rango más amplio de entradas —incluyendo promesas, estructuras de datos circulares y otros objetos complejos. Esto va más allá de lo que JSON simple puede hacer. |
| 103 | +* **No serializables**: Estas entradas no son parte de la clave de caché. Cuando intentamos almacenar estos valores en caché, devolvemos una "referencia" del servidor. Esta referencia luego es usada por Next.js para restaurar el valor original en tiempo de ejecución. |
| 104 | + |
| 105 | +Digamos que recordamos incluir `id` en la clave de caché: |
| 106 | + |
| 107 | +``` |
| 108 | +await cache(async () => { |
| 109 | + return await db |
| 110 | + .select() |
| 111 | + .from(notifications) |
| 112 | + .limit(limit) |
| 113 | + .offset(index) |
| 114 | + .where(eq(notifications.userId, id)); |
| 115 | +}, [id, index, limit]); |
| 116 | +``` |
| 117 | + |
| 118 | +Esto funciona si los valores de entrada pueden serializarse. Pero si `id` fuera un elemento React o un valor más complejo, tendríamos que serializar manualmente las claves de entrada. Considera un componente del servidor que obtiene el usuario actual basado en una propiedad `id`: |
| 119 | + |
| 120 | +``` |
| 121 | +async function Profile({ id, children }) { |
| 122 | + 'use cache'; |
| 123 | + const user = await getUser(id); |
| 124 | + |
| 125 | + return ( |
| 126 | + <> |
| 127 | + <h1>{user.name}</h1> |
| 128 | + {/* Cambiar children no rompe el caché... ¿por qué? */} |
| 129 | + {children} |
| 130 | + </> |
| 131 | + ); |
| 132 | +} |
| 133 | +``` |
| 134 | + |
| 135 | +Recorramos cómo funciona esto: |
| 136 | + |
| 137 | +1. Durante la compilación, Next.js ve la directiva `'use cache'` y transforma el código para crear una función especial del servidor que soporta caché. No ocurre almacenamiento en caché durante la compilación, sino que Next.js está configurando el mecanismo necesario para el caché en tiempo de ejecución. |
| 138 | +2. Cuando tu código llama a la "función de caché", Next.js serializa los argumentos de la función. Cualquier cosa que no sea directamente serializable, como JSX, se reemplaza con un marcador de "referencia". |
| 139 | +3. Next.js verifica si existe un resultado en caché para los argumentos serializados dados. Si no se encuentra ningún resultado, la función calcula el nuevo valor para almacenar en caché. |
| 140 | +4. Después de que la función termina, el valor de retorno se serializa. Las partes no serializables del valor de retorno se convierten nuevamente en referencias. |
| 141 | +5. El código que llamó a la función de caché deserializa la salida y evalúa las referencias. Esto permite a Next.js intercambiar las referencias con sus objetos o valores reales, lo que significa que entradas no serializables como `children` pueden mantener sus valores originales, no almacenados en caché. |
| 142 | + |
| 143 | +Esto significa que podemos almacenar en caché de manera segura _solo_ el componente `<Profile>` y no los hijos. En renderizados posteriores, `getUser()` no se llama nuevamente. El valor de `children` podría ser dinámico o un elemento almacenado en caché por separado con una vida útil de caché diferente. Esto es almacenamiento en caché componible. |
| 144 | + |
| 145 | +[Esto parece familiar...](#this-seems-familiar) |
| 146 | +-------------------------------------------- |
| 147 | + |
| 148 | +Si estás pensando "eso se siente como el mismo modelo de composición de servidor y cliente"— tienes toda la razón. A veces esto se llama el patrón "donut": |
| 149 | + |
| 150 | +* La parte **externa** de la dona es un componente del servidor que maneja la obtención de datos o lógica pesada. |
| 151 | +* El **hueco** en el centro es un componente hijo que podría tener algo de interactividad |
| 152 | + |
| 153 | +```tsx filename="app/page.tsx" |
| 154 | +export default function Page() { |
| 155 | + return ( |
| 156 | + <ServerComponent> |
| 157 | + {/* Crea un hueco hacia el cliente */} |
| 158 | + <ClientComponent /> |
| 159 | + <ServerComponent /> |
| 160 | + ); |
| 161 | +} |
| 162 | +``` |
| 163 | + |
| 164 | +`'use cache'` es lo mismo. La dona es el valor en caché del componente externo y el hueco son las referencias que se llenan en tiempo de ejecución. Es por eso que cambiar `children` no invalida toda la salida en caché. Los hijos son solo algunas referencias que se llenan más tarde. |
| 165 | + |
| 166 | +[¿Qué pasa con el etiquetado y la invalidación?](#what-about-tagging-and-invalidation) |
| 167 | +---------------------------------------------------------------------------- |
| 168 | + |
| 169 | +Puedes definir la vida del caché con diferentes [perfiles](/docs/app/api-reference/functions/cacheLife). Incluimos un conjunto de perfiles predeterminados, pero puedes definir tus propios valores personalizados si lo deseas. |
| 170 | + |
| 171 | +``` |
| 172 | +async function getUser(id) { |
| 173 | + 'use cache'; |
| 174 | + cacheLife('hours'); |
| 175 | + let res = await fetch(`https://api.vercel.app/user/${id}`); |
| 176 | + return res.json(); |
| 177 | +} |
| 178 | +``` |
| 179 | + |
| 180 | +Para invalidar una entrada de caché específica, puedes [etiquetar el caché](/docs/app/api-reference/functions/cacheTag) y luego llamar a `revalidateTag()`. Un patrón poderoso es que puedes etiquetar el caché _después_ de haber obtenido tus datos (por ejemplo, desde un CMS): |
| 181 | + |
| 182 | +``` |
| 183 | +async function getPost(postId) { |
| 184 | + 'use cache'; |
| 185 | + let res = await fetch(`https://api.vercel.app/blog/${postId}`); |
| 186 | + let data = await res.json(); |
| 187 | + cacheTag(postId, data.authorId); |
| 188 | + return data; |
| 189 | +} |
| 190 | +``` |
| 191 | + |
| 192 | +[Simple y poderoso](#simple-and-powerful) |
| 193 | +------------------------------------------- |
| 194 | + |
| 195 | +Nuestro objetivo con `'use cache'` es hacer que la lógica de almacenamiento en caché sea simple _y_ poderosa. |
| 196 | + |
| 197 | +* **Simple:** Puedes crear entradas de caché con razonamiento local. No necesitas preocuparte por efectos secundarios globales, como entradas olvidadas en la clave de caché o cambios no intencionados en otras partes de tu código base. |
| 198 | +* **Poderoso:** Puedes almacenar en caché más que solo código estáticamente analizable. Por ejemplo, valores que podrían cambiar en tiempo de ejecución, pero aún así deseas almacenar en caché el resultado después de que haya sido evaluado. |
| 199 | + |
| 200 | +`'use cache'` sigue siendo **experimental** dentro de Next.js. Nos encantaría recibir tus comentarios iniciales mientras lo pruebas. |
| 201 | + |
| 202 | +[Conoce más en la documentación](/docs/app/api-reference/directives/use-cache). |
0 commit comments