Next.js 16 Cache Components: Välimuistin hallinta use cache -direktiivillä

Johdanto

Välimuisti on aina ollut Next.js:n se kaikkein kiistanalaisin ominaisuus. Rehellisesti sanottuna, App Routerin ensimmäisissä versioissa tilanne oli melkoinen sotku — fetch()-kutsut välimuistitettiin oletuksena, eikä kukaan oikein tiennyt, mikä data on tuoretta ja mikä vanhentunutta. Bugeja syntyi ja kehittäjät turhautuivat.

Next.js 16 muutti kaiken.

Lokakuussa 2025 julkaistu versio toi mukanaan Cache Components -mallin, joka perustuu uuteen use cache -direktiiviin. Iso juttu tässä on se, että välimuisti on nyt täysin opt-in. Oletuksena mitään ei välimuistita, ja sinä kehittäjänä päätät itse, mitä välimuistitetaan ja kuinka pitkään. Ei enää arvailuja.

Tässä oppaassa käymme läpi kaiken tarvittavan Cache Components -mallin hallitsemiseen: use cache -direktiivin, cacheLife-profiilit, cacheTag-tunnisteet sekä revalidateTag- ja updateTag-funktiot. Kaikki käytännön koodiesimerkein.

Miksi Next.js uudisti välimuistimallin?

Vanha välimuistimalli oli yksinkertaisesti liian monimutkainen. Next.js 14:ssä ja 15:n alkuvaiheessa fetch()-kutsut välimuistitettiin automaattisesti, mikä johti tilanteisiin, joissa kehittäjät näkivät vanhentunutta dataa ymmärtämättä miksi. Välimuistin ohittaminen vaati erityisiä konfiguraatioita, ja virheenkorjaus oli — sanoisin — suoranaista painajaista.

Next.js-tiimi tunnusti ongelman avoimesti ja lähti suunnittelemaan kokonaan uutta lähestymistapaa. Cache Components -malli ratkaisee kolme keskeistä ongelmaa:

• Eksplisiittisyys: Välimuisti on opt-in. Mitään ei välimuistita ilman sinun nimenomaista päätöstäsi.
• Hienojakoisuus: Voit välimuistittaa kokonaisen sivun, yksittäisen komponentin tai pelkän funktion — juuri sillä tasolla, joka on järkevä kyseisessä tilanteessa.
• Hallittavuus: Välimuistin elinikä ja revalidointi konfiguroidaan selkeästi cacheLife- ja cacheTag-funktioilla.

Cache Componentsin käyttöönotto

Alkuun pääseminen on helppoa. Cache Components vaatii cacheComponents-lipun asettamisen next.config.ts-tiedostossa:

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

const nextConfig: NextConfig = {
  cacheComponents: true,
};

export default nextConfig;

Siinä kaikki. Yksi rivi konfiguraatiota ja olet valmis. Toisin kuin aiempi kokeellinen dynamicIO-lippu, cacheComponents on Next.js 16:ssa vakaa ja tuotantovalmis ominaisuus.

use cache -direktiivi käytännössä

use cache on React-direktiivi — kuten use client ja use server, mutta välimuistia varten. Se merkitsee sivun, komponentin tai funktion välimuistittavaksi, ja Next.js-kääntäjä generoi automaattisesti välimuistiavaimet parametrien perusteella. Kätevää, eikö?

Tiedostotason välimuisti

Kun use cache asetetaan tiedoston alkuun, kaikki tiedoston vientiarvot välimuistitetaan:

// app/blog/page.tsx
"use cache";

import { cacheLife } from "next/cache";

export default async function BlogPage() {
  cacheLife("days");
  const posts = await db.posts.findMany({ orderBy: { createdAt: "desc" } });

  return (
    <main>
      <h1>Blogikirjoitukset</h1>
      {posts.map((post) => (
        <article key={post.id}>
          <h2>{post.title}</h2>
          <p>{post.excerpt}</p>
        </article>
      ))}
    </main>
  );
}

Komponenttitason välimuisti

Entä jos haluat välimuistittaa vain yhden komponentin? Aseta use cache suoraan komponentin alkuun:

// app/components/product-list.tsx
import { cacheLife, cacheTag } from "next/cache";

async function ProductList({ categoryId }: { categoryId: string }) {
  "use cache";
  cacheLife("hours");
  cacheTag("products", `category-${categoryId}`);

  const products = await db.products.findMany({
    where: { categoryId },
    orderBy: { name: "asc" },
  });

  return (
    <ul>
      {products.map((product) => (
        <li key={product.id}>
          {product.name} — {product.price} €
        </li>
      ))}
    </ul>
  );
}

Huomaa, miten categoryId-parametri toimii automaattisesti välimuistiavaimena. Eri kategoriat saavat siis omat välimuistimerkintänsä — sinun ei tarvitse huolehtia avainten hallinnasta itse.

Funktiotason välimuisti

Oma suosikkini on funktiotason välimuisti. Se sopii erityisen hyvin tietokantakyselyihin ja API-kutsuihin, koska saat pidettyä välimuistilogiikan siististi datanoutofunktioiden sisällä:

// lib/data.ts
import { cacheLife, cacheTag } from "next/cache";

export async function getArticle(slug: string) {
  "use cache";
  cacheLife("days");
  cacheTag(`article-${slug}`, "articles");

  const article = await db.articles.findUnique({ where: { slug } });
  return article;
}

export async function getPopularArticles() {
  "use cache";
  cacheLife("hours");
  cacheTag("popular-articles");

  const articles = await db.articles.findMany({
    orderBy: { views: "desc" },
    take: 10,
  });
  return articles;
}

cacheLife-profiilit: välimuistin elinkaaren hallinta

cacheLife-funktio määrittää, kuinka pitkään välimuistitettu data säilyy. Se toimii kolmella aika-arvolla, ja jokainen niistä palvelee eri tarkoitusta:

• stale: Kuinka kauan asiakas käyttää välimuistidataa tarkistamatta palvelimelta.
• revalidate: Tämän ajan jälkeen seuraava pyyntö käynnistää taustapäivityksen.
• expire: Tämän ajan jälkeen välimuistimerkintä vanhenee kokonaan ja data haetaan uudelleen.

Valmiit profiilit

Useimmissa tapauksissa pärjäät hyvin Next.js:n valmiilla profiileilla:

import { cacheLife } from "next/cache";

// Lyhytikäinen data — päivittyy tiheästi
async function LiveScores() {
  "use cache";
  cacheLife("seconds");
  // stale: 0, revalidate: 1, expire: 60
  return await fetchScores();
}

// Keskipitkä välimuisti — sopii useimpiin tapauksiin
async function ProductCatalog() {
  "use cache";
  cacheLife("hours");
  // stale: 300, revalidate: 3600, expire: 86400
  return await fetchProducts();
}

// Pitkäikäinen välimuisti — harvoin muuttuva sisältö
async function Documentation() {
  "use cache";
  cacheLife("weeks");
  // stale: 604800, revalidate: 1209600, expire: 2592000
  return await fetchDocs();
}

// Maksimaalinen välimuisti — käytännössä pysyvä
async function StaticContent() {
  "use cache";
  cacheLife("max");
  // stale: Infinity, revalidate: Infinity, expire: Infinity
  return await fetchStaticData();
}

Omat profiilit next.config.ts:ssä

Valmiit profiilit eivät aina riitä, ja silloin on aika määritellä omia. Tämä on oikeastaan aika näppärä ominaisuus — voit nimetä profiilit kuvaavasti ja käyttää niitä läpi koko projektin:

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

const nextConfig: NextConfig = {
  cacheComponents: true,
  cacheLife: {
    // Blogikirjoitukset — päivittyy päivittäin
    blog: {
      stale: 3600,       // 1 tunti tuoretta
      revalidate: 86400, // 24 tuntia ennen taustapäivitystä
      expire: 604800,    // 1 viikko maksimi
    },
    // Tuotekatalogi — päivittyy useammin
    tuotteet: {
      stale: 300,        // 5 minuuttia tuoretta
      revalidate: 900,   // 15 minuuttia ennen taustapäivitystä
      expire: 3600,      // 1 tunti maksimi
    },
    // CMS-sisältö — pitkä välimuisti, revalidoidaan webhookilla
    cms: {
      stale: 86400,      // 24 tuntia tuoretta
      revalidate: 604800,// 1 viikko ennen taustapäivitystä
      expire: 2592000,   // 30 päivää maksimi
    },
  },
};

export default nextConfig;

Ja omien profiilien käyttö koodissa on yhtä suoraviivaista kuin valmiiden:

import { cacheLife, cacheTag } from "next/cache";

async function getBlogPost(slug: string) {
  "use cache";
  cacheLife("blog");  // Käyttää omaa profiilia
  cacheTag(`post-${slug}`);

  const post = await db.posts.findUnique({ where: { slug } });
  return post;
}

async function getProductList() {
  "use cache";
  cacheLife("tuotteet");  // Käyttää omaa profiilia
  cacheTag("product-list");

  return await db.products.findMany();
}

Inline-profiili kertaluonteiseen käyttöön

Joskus tarvitset erityistä välimuistikonfiguraatiota vain yhdessä kohtaa. Silloin ei kannata luoda kokonaista profiilia — voit määritellä arvot suoraan:

async function getExchangeRates() {
  "use cache";
  cacheLife({
    stale: 60,        // 1 minuutti tuoretta
    revalidate: 300,  // 5 minuuttia ennen taustapäivitystä
    expire: 600,      // 10 minuuttia maksimi
  });

  const rates = await fetch("https://api.exchangerate.host/latest");
  return rates.json();
}

cacheTag ja välimuistin invalidointi

Okei, nyt päästään siihen osaan, joka tekee koko järjestelmästä todella tehokkaan. Välimuistitunnisteet (cacheTag) ovat avain kohdennettuun invalidointiin — niillä voit tyhjentää täsmälleen oikeat välimuistimerkinnät ilman, että koko välimuisti nollautuu.

Tunnisteiden asettaminen

import { cacheTag } from "next/cache";

async function getProduct(id: string) {
  "use cache";
  cacheTag("products", `product-${id}`);

  return await db.products.findUnique({ where: { id } });
}

async function getCategoryProducts(categoryId: string) {
  "use cache";
  cacheTag("products", `category-${categoryId}`);

  return await db.products.findMany({ where: { categoryId } });
}

Molemmat funktiot jakavat products-tunnisteen. Kun invalidoit tuon tunnisteen, molempien välimuistit tyhjennetään. Mutta voit myös invalioida pelkästään yksittäisen tuotteen tunnisteella product-123. Tämä joustavuus on todella arvokasta tuotantoympäristössä.

revalidateTag — taustapäivitys

revalidateTag merkitsee välimuistidatan vanhentuneeksi ja käynnistää taustapäivityksen seuraavalla pyynnöllä. Käyttäjä näkee vielä vanhan datan, kunnes uusi on valmis — eli käyttökokemus pysyy sujuvana:

// app/api/revalidate/route.ts
import { revalidateTag } from "next/cache";
import { NextRequest } from "next/server";

export async function POST(request: NextRequest) {
  const { tag, secret } = await request.json();

  // Tarkista webhook-salaisuus
  if (secret !== process.env.REVALIDATION_SECRET) {
    return Response.json({ error: "Virheellinen salaisuus" }, { status: 401 });
  }

  revalidateTag(tag, "max");
  return Response.json({ revalidated: true, tag });
}

Tärkeä muutos: revalidateTag vaatii nyt toisen argumentin. Profiili "max" käyttää stale-while-revalidate-semantiikkaa — vanha data palvelee käyttäjiä, kunnes uusi on haettu taustalla. Yhden argumentin muoto on vanhentunut, joten muista päivittää koodisi.

updateTag — välitön päivitys Server Actioneissa

updateTag on suunniteltu nimenomaan Server Actioneihin, joissa käyttäjän pitää nähdä muutoksensa heti. Se tyhjentää välimuistin välittömästi, ja seuraava pyyntö odottaa tuoretta dataa (niin sanottu read-your-own-writes -periaate):

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

import { updateTag } from "next/cache";

export async function updateProduct(id: string, data: ProductInput) {
  await db.products.update({
    where: { id },
    data,
  });

  // Välitön välimuistin tyhjennys — käyttäjä näkee muutoksen heti
  updateTag(`product-${id}`);
  updateTag("products");
}

export async function deleteProduct(id: string) {
  await db.products.delete({ where: { id } });

  updateTag(`product-${id}`);
  updateTag("products");
}

Milloin käyttää revalidateTag vs. updateTag?

Tämä on yksi yleisimmistä kysymyksistä, ja ero on onneksi selkeä:

• revalidateTag: Kun ulkoinen lähde (CMS, webhook) ilmoittaa muutoksesta. Käyttäjä ei odota välitöntä päivitystä. Toimii Server Actioneissa ja Route Handlereissa.
• updateTag: Kun käyttäjä itse tekee muutoksen (lomake, painike). Käyttäjä odottaa näkevänsä muutoksensa heti. Toimii vain Server Actioneissa.

Peukalosääntö: jos käyttäjä painoi nappia, käytä updateTag. Jos taustajärjestelmä ilmoitti muutoksesta, käytä revalidateTag.

Kolme välimuistidirektiiviä: use cache vs. remote vs. private

Next.js 16 tarjoaa kolme eri use cache -varianttia, ja jokaisella on oma käyttötarkoituksensa. Käydään ne läpi.

use cache — oletusvälimuisti

Tallentaa datan palvelimen muistiin. Serverless-ympäristöissä (kuten Vercel) muisti ei jakaudu instanssien välillä, joten välimuisti voi nollautua melko usein. Silti hyödyllinen, koska se ohjaa Next.js:n esihakua ja määrittää stale-ajat asiakasnavigointiin.

use cache: remote — jaettu välimuisti

Tallentaa datan ulkoiseen välimuistiin kuten Redisiin tai KV-tietokantaan. Tämä on se vaihtoehto, jonka haluat, kun välimuistin pitää toimia yhdenmukaisesti kaikkien palvelininstanssien välillä:

async function getGlobalConfig() {
  "use cache: remote";
  cacheLife("days");
  cacheTag("global-config");

  return await db.config.findFirst();
}

Erityisen hyödyllinen, kun datalähteesi ei kestä samanaikaisia revalidointipyyntöjä — esimerkiksi nopeusrajoitettu CMS-API.

use cache: private — käyttäjäkohtainen välimuisti

use cache: private on (toistaiseksi kokeellinen) direktiivi, joka sallii evästeiden lukemisen välimuistiskoopin sisällä. Se on tarkoitettu käyttäjäkohtaiseen dataan, jota ei koskaan jaeta käyttäjien välillä:

import { cookies } from "next/headers";

async function getUserDashboard() {
  "use cache: private";
  cacheLife("minutes");

  const session = (await cookies()).get("session-token");
  // Käyttäjäkohtainen data välimuistissa
  const dashboard = await fetchDashboard(session?.value);
  return dashboard;
}

Huom: Käytä use cache: private vain silloin, kun et voi järkevästi refaktoroida koodia välittämään ajonaikaista dataa parametreina. Useimmissa tapauksissa parempi ratkaisu on lukea evästeet välimuistiskoopin ulkopuolella ja välittää arvot funktiolle argumentteina.

Käytännön suunnittelumallit

Nyt kun teoria on hallussa, katsotaan muutama käytännön malli, joita olen nähnyt toimivan hyvin oikeissa projekteissa.

Malli 1: Ehdollinen välimuistiaika

Eri tulokset voivat ansaita eri välimuistiajat — ja tämä on täysin sallittua:

async function getArticle(slug: string) {
  "use cache";
  cacheTag(`article-${slug}`);

  const article = await db.articles.findUnique({ where: { slug } });

  if (!article) {
    cacheLife("minutes");  // Ei löytynyt — tarkista pian uudelleen
    return null;
  }

  if (article.status === "draft") {
    cacheLife("seconds");  // Luonnos — päivittyy usein
    return article;
  }

  cacheLife("days");  // Julkaistu — harvoin muuttuu
  return article;
}

Tämä on oikeasti tosi kätevä malli. Tyhjälle tulokselle kannattaa antaa lyhyt välimuistiaika, koska kyseinen artikkeli saatetaan luoda pian. Julkaistulle sisällölle taas pidempi aika on järkevä.

Malli 2: Donitsi-malli (staattinen kuori + dynaaminen sisältö)

Tämä on yksi suosikeistani. Välimuistita ulompi komponentti ja jätä sisäinen dynaaminen osa välimuistin ulkopuolelle:

// Välimuistitettu kuori
async function CachedLayout({ children }: { children: React.ReactNode }) {
  "use cache";
  cacheLife("days");

  const navigation = await getNavigation();
  const footer = await getFooter();

  return (
    <div>
      <nav>{navigation}</nav>
      <main>{children}</main>
      <footer>{footer}</footer>
    </div>
  );
}

// Käyttö sivulla — children ei välimuistita
export default async function DashboardPage() {
  return (
    <CachedLayout>
      <Suspense fallback={<Loading />}>
        <DynamicContent />
      </Suspense>
    </CachedLayout>
  );
}

Navigaatio ja footer tulevat välimuistista, mutta varsinainen sivun sisältö renderöidään aina tuoreena. Yksinkertaista mutta tehokasta.

Malli 3: CMS-integraatio webhookeilla

Tämä on hyvin tyypillinen tuotantokäyttötapaus — pitkä välimuistiaika yhdistettynä on-demand-revalidointiin CMS-webhookin kautta:

// lib/cms.ts
import { cacheLife, cacheTag } from "next/cache";

export async function getCMSPage(slug: string) {
  "use cache";
  cacheLife("cms");  // Oma profiili: pitkä välimuisti
  cacheTag(`cms-page-${slug}`, "cms-pages");

  const response = await fetch(
    `${process.env.CMS_API_URL}/pages/${slug}`,
    { headers: { Authorization: `Bearer ${process.env.CMS_TOKEN}` } }
  );
  return response.json();
}

// app/api/cms-webhook/route.ts
import { revalidateTag } from "next/cache";

export async function POST(request: Request) {
  const payload = await request.json();
  const secret = request.headers.get("x-webhook-secret");

  if (secret !== process.env.CMS_WEBHOOK_SECRET) {
    return Response.json({ error: "Unauthorized" }, { status: 401 });
  }

  // Revalidoi vain muuttuneet sivut
  if (payload.slug) {
    revalidateTag(`cms-page-${payload.slug}`, "max");
  } else {
    revalidateTag("cms-pages", "max");
  }

  return Response.json({ revalidated: true });
}

Malli 4: Kolmitasoinen välimuisti

Ja lopuksi malli, jossa yhdistetään kaikki kolme direktiiviä samassa sovelluksessa. Tämä kuvastaa hyvin sitä, miltä välimuististrategia voi näyttää isommassa projektissa:

// Staattinen tuotedata — in-memory-välimuisti
async function getProductInfo(id: string) {
  "use cache";
  cacheLife("days");
  cacheTag(`product-${id}`);
  return await db.products.findUnique({ where: { id } });
}

// Jaettu hintadata — remote-välimuisti kaikille instansseille
async function getProductPricing(id: string) {
  "use cache: remote";
  cacheLife("hours");
  cacheTag(`pricing-${id}`);
  return await pricingService.getPrice(id);
}

// Käyttäjäkohtaiset suositukset
async function getUserRecommendations() {
  "use cache: private";
  cacheLife("minutes");
  const session = (await cookies()).get("session-token");
  return await recommendationService.get(session?.value);
}

Virheenkorjaus ja välimuistin seuranta

Välimuistin debuggaaminen voi olla turhauttavaa, myönnetään. Onneksi Next.js tarjoaa ympäristömuuttujan, jolla saat yksityiskohtaisen lokin välimuistioperaatioista:

# Kehitysympäristö
NEXT_PRIVATE_DEBUG_CACHE=1 npm run dev

# Tuotantoympäristö
NEXT_PRIVATE_DEBUG_CACHE=1 npm run start

Tämä tulostaa konsoliin jokaisen välimuistiosuman, -ohituksen ja -päivityksen. Todella hyödyllinen kehitysvaiheessa — suosittelen pitämään tämän päällä aina, kun työskentelet välimuistin kanssa.

Yleiset virheet ja niiden ratkaisut

• "Uncached data was accessed outside of Suspense": Asynkroninen komponentti ei ole use cache -skoopissa eikä <Suspense>-rajauksessa. Lisää jompikumpi, niin virhe katoaa.
• Välimuisti ei päivity: Tarkista, että cacheTag-tunnisteet täsmäävät revalidateTag- tai updateTag-kutsuissa. Kirjoitusvirhe tunnisteessa on yllättävän yleinen syy.
• Evästeet eivät toimi use cache -skoopissa: use cache ja use cache: remote eivät salli ajonaikaisten arvojen lukemista. Käytä use cache: private tai välitä arvot parametreina.
• Asiakas näyttää aina vanhaa dataa: Next.js:n asiakas-reititin käyttää vähintään 30 sekunnin stale-aikaa riippumatta sinun konfiguraatiostasi. Tämä on hyvä tietää.

Yhteenveto

Next.js 16:n Cache Components -malli on iso askel eteenpäin verrattuna aiempaan implisiittiseen välimuistiin. Kootaan tärkeimmät opit yhteen:

• use cache tekee välimuistista eksplisiittisen — ei enää arvailua siitä, mikä on välimuistissa ja mikä ei.
• cacheLife antaa tarkan hallinnan välimuistin elinkareen. Aloita valmiilla profiileilla ja tee omia tarpeen mukaan.
• cacheTag mahdollistaa kohdistetun invalidoinnin — yksittäisen tuotteen päivitys ei tyhjennä koko välimuistia.
• revalidateTag sopii taustapäivityksiin (CMS-webhookit), updateTag välittömiin päivityksiin (käyttäjän toiminnot).
• Kolme direktiiviä (use cache, use cache: remote, use cache: private) kattavat eri käyttötapaukset yksinkertaisesta monimutkaiseen.

Suosittelen aloittamaan valmiilla profiileilla, siirtymään omiin profiileihin tarpeen mukaan, ja käyttämään NEXT_PRIVATE_DEBUG_CACHE=1 -ympäristömuuttujaa varmistamaan, että kaikki toimii niin kuin pitää. Kun malli kerran naksahtaa paikalleen, se tuntuu todella luontevalta.

Usein kysytyt kysymykset

Pitääkö use cache lisätä jokaiseen komponenttiin?

Ei todellakaan. Lisää use cache vain sinne, missä siitä on konkreettista hyötyä — tietokantakyselyihin, API-kutsuihin tai raskaaseen laskentaan. Ilman direktiiviä koodi suoritetaan jokaisella pyynnöllä, ja se on ihan oikea toiminta dynaamiselle datalle. Älä välimuistita kaikkea "varmuuden vuoksi".

Miten use cache eroaa vanhasta fetch-välimuistista?

Vanha fetch()-välimuisti oli implisiittinen — kutsut välimuistitettiin automaattisesti, ja sinun piti erikseen ohittaa välimuisti (cache: "no-store"). use cache toimii päinvastoin: oletuksena mitään ei välimuistita. Lisäksi use cache toimii minkä tahansa asynkronisen operaation kanssa, ei pelkästään fetch-kutsujen kanssa.

Voiko use cache -komponentti sisältää Client Componenteja?

Kyllä voi. Donitsi-malli on tähän täydellinen: välimuistitettu Server Component renderöi staattisen kuoren ja välittää dynaamisen sisällön children-propin kautta. Client Componentit renderöidään normaalisti asiakkaalla, mutta ympäröivän Server Componentin tuotos tulee välimuistista.

Toimiiko Cache Components Vercelin ulkopuolella?

Kyllä. Perus use cache ja use cache: private tallentavat datan muistiin ja toimivat millä tahansa alustalla. use cache: remote vaatii ulkoisen välimuistijärjestelmän (esim. Redis), jonka voit konfiguroida cacheHandlers-asetuksella next.config.ts-tiedostossa. Eli kyllä, tämä toimii myös itse hostatuissa ympäristöissä.

Miten estän välimuistiin liittyvät tietoturvaongelmat?

Tämä on tärkeä kysymys. Älä koskaan välimuistita käyttäjäkohtaista dataa use cache- tai use cache: remote -direktiivillä — nämä jakavat datan kaikkien käyttäjien kesken. Käyttäjäkohtainen data kuuluu use cache: private -skooppiin tai dynaamiseen renderöintiin ilman välimuistia. Tarkista aina, ettei välimuistiin päädy henkilökohtaisia tietoja, sessiotietoja tai pääsynhallintaan liittyvää dataa.