Data fetching আর cache — fetch, revalidate আর streaming

১ · Server component-এ ডেটা আনা: সরাসরি ডেটাবেস, নাকি নিজের API

পর্ব ৫২-তে (Server Component আর Client Component) দেখেছেন, একটি Server Component শুধু server-এ চলে, আর তার কোড browser-এ যায় না। এর সবচেয়ে বড় সুবিধা ডেটা আনায়। Component নিজেই async হতে পারে। ভেতরে সরাসরি await করে ডেটাবেস পড়া যায়। useEffect, loading state বা আলাদা API লাগে না।

বাজারঘরের প্রকল্পে ডেটাবেস ইচ্ছা করে ধীর রাখা হয়েছে, যাতে সময় চোখে পড়ে। একটি JSON ফাইল পড়ার আগে প্রতিটি query নির্দিষ্ট সময় ঘুমায়: পণ্য-তালিকা ৩০০ ms, একটি পণ্য ২০০ ms, স্টক ৪০০ ms, রিভিউ ১,২০০ ms. প্রতিটি query একটি log লাইন লেখে, ফলে কখন ডেটাবেসে যাওয়া হলো তা গুনে দেখা যায়।

async function query<T>(label: string, ms: number, pick: (s: Shop) => T) {
  const t0 = performance.now();
  await sleep(ms);                                   // ধীর ডেটাবেসের অনুকরণ
  const shop: Shop = JSON.parse(await readFile(FILE, "utf8"));
  calls++;
  console.log(`[db #${calls}] ${label} ${Math.round(performance.now() - t0)}ms`);
  return pick(shop);
}
export const db = {
  listProducts: () => query("SELECT products", 300, (s) => s.products),
  getProduct: (id: number) => query(`SELECT product ${id}`, 200, (s) => s.products.find((p) => p.id === id) ?? null),
  getReviews: (id: number) => query(`SELECT reviews ${id}`, 1200, (s) => s.reviews[id] ?? []),
  getStock: (id: number) => query(`SELECT stock ${id}`, 400, (s) => s.stock[id] ?? 0),
};

এবার একই পাতায় দুইভাবে পণ্য-তালিকা আনা হলো: একবার সরাসরি db.listProducts(), আরেকবার নিজের /api/products route-কে fetch দিয়ে ডেকে। Route-টি ভেতরে আবার সেই একই query চালায়।

সত্যিকারের run · Next.js 16.4.4, next build তারপর next start · একটি local কম্পিউটারে একবার

[db #19] SELECT products 304ms
[direct] 3 products 304ms
[db #1] SELECT products 305ms
[via-api] 3 products 329ms

দুটি জিনিস লক্ষ করুন। প্রথমত, API পথে ২৫ ms বেশি লাগল। একই কম্পিউটারে HTTP অনুরোধ, JSON বানানো আর আবার পড়ার খরচ এটি। Server আলাদা যন্ত্রে বা অন্য region-এ থাকলে এই খরচ আরও বাড়ে। দ্বিতীয়ত, counter হঠাৎ #1 হয়ে গেছে। Route handler আর পাতা build-এর পর আলাদা bundle-এ থাকে, তাই module-এর ভেতরের calls ভ্যারিয়েবলও আলাদা। Module-এর ভেতরের ভ্যারিয়েবলে জমানো state তাই নির্ভরযোগ্য নয়। এজন্যই এই প্রকল্পে ডেটা ফাইলে রাখা হয়েছে।

২ · Request waterfall বনাম Promise.all

পণ্যের পাতায় তিনটি জিনিস লাগে: পণ্য, স্টক আর রিভিউ। তিনটি একে অপরের ওপর নির্ভর করে না। তবু সহজ কোড এমন হয়:

const product = await db.getProduct(1);   // ২০০ ms
const stock = await db.getStock(1);       // ৪০০ ms, আগেরটি শেষ হলে শুরু
const reviews = await db.getReviews(1);   // ১২০০ ms, তারও পরে

প্রতিটি await থেমে থাকে আগেরটির জন্য। একে বলে request waterfall: সিঁড়ির মতো একটির পর একটি। সমাধান হলো সবগুলো একসাথে শুরু করা, তারপর একবারে অপেক্ষা করা। এটাই Promise.all:

const [product, stock, reviews] = await Promise.all([
  db.getProduct(1), db.getStock(1), db.getReviews(1),   // তিনটি একসাথে শুরু
]);

সত্যিকারের run · Next.js 16.4.4 · একটি local কম্পিউটারে একবার · server log আর পুরো পাতা আসার সময়

[db #13] SELECT product 1 201ms
[db #14] SELECT stock 1 411ms
[db #15] SELECT reviews 1 1216ms
[waterfall] 1829ms            পুরো পাতা: 1886 ms
[db #16] SELECT product 1 202ms
[db #17] SELECT stock 1 406ms
[db #18] SELECT reviews 1 1205ms
[parallel] 1206ms             পুরো পাতা: 1253 ms

হিসাবের নিয়ম

ধরা যাক query-গুলোর সময় t₁, t₂, …, tₙ. একটির পর একটি চালালে মোট সময় Σtᵢ. স্বাধীন হলে একসাথে চালিয়ে মোট সময় max(tᵢ). কিছু query আগের ফলের ওপর নির্ভর করলে (যেমন আগে ব্যবহারকারী, তারপর তাঁর অর্ডার) সেই শিকলটুকু একসাথে করা যায় না। তখন মোট সময় হলো সবচেয়ে লম্বা নির্ভরতার পথ, যাকে বলে critical path.

মাপা সংখ্যা হিসাবের খুব কাছে: ১,৮২৯ বনাম ১,২০৬ ms. বাড়তি কয়েক ms আসে timer আর ফাইল পড়া থেকে। নিচের মডেলে একটি নকল ঘড়ি আছে, তাই প্রতিবার হুবহু একই সংখ্যা আসে। এটি শেখানোর মডেল, Next.js নয়।

// শেখানোর মডেল: নকল ঘড়ি, তাই প্রতিবার একই সংখ্যা আসে
let now = 0, timers = [];
const sleep = (ms) => new Promise((r) => timers.push({ at: now + ms, r }));
const log = [];

async function query(name, ms) {
  log.push(`  t=${String(now).padStart(3)}ms start ${name}`);
  await sleep(ms);
  log.push(`  t=${String(now).padStart(3)}ms end   ${name}`);
  return name;
}
async function waterfall() {
  const p = await query('product', 200);   // শেষ হলে তবেই পরেরটি
  const s = await query('stock', 400);
  const r = await query('reviews', 1200);
  return [p, s, r];
}
async function parallel() {               // তিনটি একসাথে শুরু
  return Promise.all([query('product', 200), query('stock', 400), query('reviews', 1200)]);
}
async function run(label, fn) {           // নকল ঘড়ি চালানোর ছোট scheduler
  now = 0; timers = []; log.length = 0;
  let done = false;
  fn().then(() => { done = true; });
  while (!done) {
    await new Promise((r) => setImmediate(r));
    if (done || !timers.length) break;
    timers.sort((a, b) => a.at - b.at);
    const t = timers.shift(); now = t.at; t.r();
  }
  console.log(`${label}: total ${now} ms\n${log.join('\n')}`);
}
run('waterfall', waterfall).then(() => run('Promise.all', parallel));

৩ · React cache(): একটি অনুরোধে একই query একবার

বড় পাতায় একই ডেটা অনেক জায়গায় লাগে। পণ্যের ক্যাটাগরির নাম লাগে header-এ, breadcrumb-এ আর sidebar-এ। তিনটি component তিনবার ডাকলে ডেটাবেসে তিনটি query যায়। Prop দিয়ে নিচে পাঠানো যায়, কিন্তু তাতে component-গুলো জড়িয়ে যায়।

React একটি ছোট সমাধান দেয়: React cache(). একটি ফাংশনকে cache() দিয়ে মুড়ে দিলে একটি server অনুরোধের ভেতরে একই argument-এ দ্বিতীয়বার ডাকলে আগের ফলটিই ফেরে। অনুরোধ শেষ হলে সেই স্মৃতি মুছে যায়। এটি deduplication, স্থায়ী cache নয়।

import { cache } from "react";
// একটি অনুরোধের ভেতরে একবারই ডেটাবেস
export const getCategoryOnce = cache((id: number) => db.getCategory(id));

পরীক্ষার পাতায় তিনটি component সাধারণ db.getCategory(5) ডাকল, আর তিনটি ডাকল getCategoryOnce(5):

সত্যিকারের run · Next.js 16.4.4, React 19.3.0 · একটি local কম্পিউটারে একবার · একটি অনুরোধ

[db #20] SELECT category 5 104ms
[db #21] SELECT category 5 104ms
[db #22] SELECT category 5 104ms
[db #23] SELECT category 5 104ms

ছয়বার ডাকা হলো, query গেল চারটি: সাধারণ পথের তিনটি, আর cache()-এর পথে একটি। Next.js নিজের fetch-এর ক্ষেত্রেও একই কাজ করে: একই render-এ একই URL আর একই option-এর GET একবারই যায়। একে Next.js-এর docs বলে memoization. কিন্তু ORM বা নিজের ডেটাবেস ফাংশনের জন্য cache() আপনাকেই দিতে হয়।

ভেতরে কী ঘটে, নিচের মডেলে দেখুন। প্রতিটি অনুরোধ নিজের একটি Map পায়। Node-এর AsyncLocalStorage সেই Map-কে অনুরোধের সব async কাজের সাথে বেঁধে রাখে। এটি শেখানোর মডেল; React-এর ভেতরের কোড এমন নয়, তবে আচরণ একই।

// শেখানোর মডেল: React cache()-এর মতো, প্রতিটি অনুরোধের নিজের Map
const { AsyncLocalStorage } = require('node:async_hooks');
const requestScope = new AsyncLocalStorage();
let dbHits = 0;

async function getCategory(id) {
  dbHits++;
  await new Promise((r) => setTimeout(r, 5));      // ধীর ডেটাবেস
  return id === 5 ? 'grocery' : '?';
}
function cache(fn) {
  return (...args) => {
    const memo = requestScope.getStore();           // এই অনুরোধের Map
    if (!memo) return fn(...args);                  // অনুরোধের বাইরে: dedupe নেই
    const key = JSON.stringify(args);
    if (!memo.has(key)) memo.set(key, fn(...args)); // Promise-টাই জমা থাকে
    return memo.get(key);
  };
}
const getCategoryOnce = cache(getCategory);

function renderPage(reqId, f) {
  return requestScope.run(new Map(), async () => {
    const before = dbHits;
    const parts = await Promise.all([f(5), f(5), f(5)]); // header, breadcrumb, sidebar
    console.log(`req ${reqId}: ${parts.join(',')}  db queries=${dbHits - before}`);
  });
}
(async () => {
  await renderPage(1, getCategory);
  await renderPage(2, getCategoryOnce);
  await renderPage(3, getCategoryOnce);             // নতুন অনুরোধ, নতুন Map
  await getCategoryOnce(5); await getCategoryOnce(5);
  console.log(`outside a request: total db queries=${dbHits}`);
})();

৪ · Next.js 16-এর cache: "use cache" আর cacheLife

"Default" কথাটি তাই সবসময় একটি config-এর সাথে বলতে হয়। এই পর্বের সব run দুটির একটি থেকে: (ক) create-next-app@16.4.4 --yes-এর template, যার next.config.ts-এ লেখা ছিল cacheComponents: true আর partialPrefetching: true; অথবা (খ) একই প্রকল্প, next.config.ts খালি করে, অর্থাৎ cacheComponents বন্ধ। যেখানে আলাদা করে বলা নেই, সেখানে (ক)। প্রকল্পের config এটি:

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

এখন নিয়ম সহজ। কোনো async ফাংশন বা component-এর শুরুতে "use cache" লিখলে তার ফল জমা থাকে। Argument-গুলো cache key-এর অংশ, তাই getProduct(1) আর getProduct(2) আলাদা জমা। কতক্ষণ থাকবে তা বলে cacheLife, আর কোন দলের তা বলে cacheTag:

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

// সবার জন্য একই তালিকা: cache-এ রাখা, ট্যাগ 'products'
export async function getProducts() {
  "use cache";
  cacheLife("hours");
  cacheTag("products");
  return db.listProducts();
}

export async function getProduct(id: number) {
  "use cache";
  cacheLife("hours");
  cacheTag("products", `product-${id}`);
  return db.getProduct(id);
}

যা cache করা নেই, যেমন আজকের স্টক, তা প্রতিটি অনুরোধে চলে। Next.js চায় আপনি এমন অংশকে Suspense-এ রাখুন। connection() ডাকলে Next.js বোঝে "এই অংশ build-এ বানানো যাবে না, অনুরোধ এলে চালাতে হবে":

export default async function ProductsPage() {
  const products = await getProducts();          // cache থেকে
  return (
    <main>
      <h1>বাজারঘর — সব পণ্য</h1>
      <ul>{products.map((p) => <li key={p.id}>…{p.name} — ৳{p.price}</li>)}</ul>
      <Suspense fallback={<p>আজকের স্টক আসছে…</p>}>
        <TodayStock />
      </Suspense>
    </main>
  );
}
async function TodayStock() {
  await connection();                            // প্রতিটি অনুরোধে নতুন করে
  const n = await db.getStock(1);
  return <p>সরিষার তেল স্টকে আছে: {n}টি</p>;
}

Build করলে Next.js প্রতিটি route-এর একটি চিহ্ন দেয়। Path ছোট করে ~/bazarghar লেখা হয়েছে।

সত্যিকারের run · ~/bazarghar$ npx next build · Next.js 16.4.4 (Turbopack), Node.js 24

▲ Next.js 16.4.4 (Turbopack)
- Cache Components enabled
- Partial Prefetching enabled
✓ Compiled successfully in 496ms
…
[db #1] SELECT product 1 206ms
[db #2] SELECT products 310ms
✓ Generating static pages using 16 workers (15/15) in 1255ms

Route (app)           Revalidate  Expire
┌ ○ /
├ ◐ /account
├ ƒ /api/price
├ ƒ /blocking
├ ◐ /products                 1h      1d
├   /products/[id]
│ ├ ◐ /products/[id]
│ └ ◐ /products/1             1h      1d
…
○  (Static)             prerendered as static content
◐  (Partial Prerender)  prerendered as static HTML with dynamic server-streamed content
ƒ  (Dynamic)            server-rendered on demand

পড়ার কৌশল: ◐ মানে পাতার একটি static shell build-এর সময় তৈরি হয়ে আছে, আর Suspense-এর ভেতরের অংশ অনুরোধের সময় stream হবে। একে Next.js বলে Partial Prerendering; বিস্তারিত পর্ব ৫৫-তে (SSR, SSG, ISR আর partial prerendering). /products-এর পাশে 1h আর 1d এসেছে cacheLife("hours") থেকে। আর build-এর সময়েই ডেটাবেসে দুটি query গেছে: তালিকা আর পণ্য ১-এর shell বানাতে। এরপর server চালু করে /products খুললে log-এ SELECT products আসে না, শুধু স্টকের query আসে।

cacheComponents বন্ধ থাকলে কী হয়

একই প্রকল্পে config খালি করে build দেওয়া হলো (config খ)। প্রথমে build-ই থামল, কারণ "use cache" আর instant এই flag ছাড়া চলে না:

সত্যিকারের run · config খ (cacheComponents বন্ধ) · Next.js 16.4.4 · build ব্যর্থ, অংশবিশেষ

./app/blocking/page.tsx:5:14
Error: Route segment config "instant" requires `nextConfig.cacheComponents` to be enabled.
./lib/data.ts:7:3
Error: To use "use cache", please enable the feature flag `cacheComponents` in your Next.js config.

তারপর "use cache"-এর লাইনগুলো সরিয়ে, /blocking বাদ দিয়ে, আর একটি নতুন পাতা /plain যোগ করে আবার build. /plain শুধু await getProducts() করে, কোনো connection() বা cookies() ছাড়া।

সত্যিকারের run · config খ · Next.js 16.4.4 · route table-এর অংশ আর তারপর next start-এ অনুরোধ · একটি local কম্পিউটারে একবার

[db #3] SELECT products 303ms        ← build-এর সময়
├ ○ /plain
├ ƒ /products
├ ƒ /products/[id]
├ ƒ /account
…
GET /plain → ৳320   GET /products → ৳320
POST /api/price id=1 340 → {"ok":true,"id":1,"price":340}
GET /plain → ৳320   GET /products → ৳340
GET /plain → ৳320   GET /products → ৳340
/plain-এর header: x-nextjs-cache: HIT · Cache-Control: s-maxage=31536000

শেষ সারিটিই আগের মডেলের পরিচিত ফাঁদ। /plain কোনো cache-এর কথা বলেনি, তবু build-এর সময়ের দাম জমে গেল, আর revalidateTag('products', 'max')-ও তাকে ছুঁতে পারল না, কারণ তার গায়ে কোনো ট্যাগ নেই। এই config-এ তাকে নতুন করতে revalidatePath('/plain') বা নতুন deploy লাগত। Cache Components এই নীরব সিদ্ধান্তটিকেই build error বানিয়ে আপনার সামনে আনে।

তিনটি সংখ্যার মানে: stale হলো browser কতক্ষণ প্রশ্ন না করে নিজের কপি ব্যবহার করবে। revalidate পার হলে server পরের অনুরোধে পুরোনো কপি দিয়েই পেছনে নতুন বানায়। expire পার হলে পুরোনো কপি আর দেওয়া হয় না, অনুরোধকে নতুন ডেটার জন্য অপেক্ষা করতে হয়। Docs অনুযায়ী seconds profile বা ৫ মিনিটের কম expire-এর cache "short-lived" ধরা হয়, আর সেটি static shell-এ ঢোকে না।

বাজারঘরের দুই নম্বর পণ্য build-এ বানানো হয়নি, কারণ generateStaticParams শুধু 1 ফেরায়। তাই প্রথম ক্রেতা একটি cache miss দেখবেন, আর দ্বিতীয়জন hit. নিচে আসল run ধাপে ধাপে দেখুন:

GET /products/2
"use cache" store-এ getProduct(2) নেই

<template> <p>পণ্যের পাতা আসছে…</p>
params অজানা ছিল, তাই loading.tsx-এর fallback

[db #4] SELECT product 2 206ms
+257 ms: <h1>মিনিকেট চাল ৫ কেজি … <p>রিভিউ লোড হচ্ছে…

[db #5] SELECT reviews 2 1214ms
+1463 ms: <li>চাল ঝরঝরে
পুরো পাতা: 1467 ms

+31 ms: <h1>মিনিকেট চাল ৫ কেজি … দাম
[db #6] SELECT reviews 2 1205ms   ← শুধু এটি
পুরো পাতা: 1252 ms

কত সাশ্রয়: একটি হিসাব

ধরা যাক (অনুমিত সংখ্যা) বাজারঘরের পণ্য-তালিকা ঘণ্টায় ১০,০০০ বার খোলা হয়, আর তালিকার query ৩০০ ms. Cache ছাড়া ডেটাবেস ঘণ্টায় ১০,০০০ × ০.৩ = ৩,০০০ সেকেন্ড কাজ করে, অর্থাৎ গড়ে প্রায় ০.৮৩টি query সবসময় চলছে। cacheLife("hours") দিলে প্রতিটি server instance ঘণ্টায় মোটামুটি একবার নতুন বানায়। চারটি instance থাকলে ঘণ্টায় প্রায় ৪টি query, মোট ১.২ সেকেন্ড। Hit rate দাঁড়ায় (১০,০০০ − ৪) ÷ ১০,০০০ ≈ ৯৯.৯৬%. দাম হলো সতেজতা: দাম বদলের পর এক ঘণ্টা পর্যন্ত পুরোনো তালিকা দেখা যেতে পারে। সেই ফাঁক বন্ধ করে পরের অংশের ট্যাগ।

৫ · দাম বদলালে: cacheTag, revalidateTag, updateTag

সময় ধরে নতুন করা (cacheLife) অনুমানের ওপর চলে। কিন্তু দোকানি দাম বদলালে আপনি ঠিক জানেন কোন ডেটা পুরোনো হলো। তখন ট্যাগ ধরে বলা যায়: "products ট্যাগের সব জমা পুরোনো।" এটি on-demand revalidation.

বাজারঘরে দাম বদলের জন্য একটি Route handler আছে। এতে নকল একটি admin key যাচাই হয় (আসল প্রকল্পে session আর role, পর্ব ৪৮), ইনপুট যাচাই হয় (পর্ব ২৭-এর মতো), তারপর ডেটাবেস বদলে ট্যাগ পুরোনো চিহ্নিত হয়:

import { revalidateTag } from "next/cache";
import { db } from "@/lib/db";

export async function POST(req: Request) {
  if (req.headers.get("x-admin-key") !== process.env.ADMIN_KEY) {
    return Response.json({ error: "unauthorized" }, { status: 401 });
  }
  const { id, price } = await req.json();
  if (!Number.isInteger(id) || !Number.isInteger(price) || price <= 0) {
    return Response.json({ error: "bad input" }, { status: 400 });
  }
  if (!(await db.setPrice(id, price))) return Response.json({ error: "not found" }, { status: 404 });
  revalidateTag("products", "max");
  return Response.json({ ok: true, id, price });
}

সত্যিকারের run · Next.js 16.4.4, next start, ADMIN_KEY=example-secret · একটি local কম্পিউটারে একবার · প্রতিটি লাইন একটি অনুরোধ

GET  /products      → ৳320 ৳410 ৳150
GET  /products/1    → ৳320
POST /api/price (key ছাড়া)          → {"error":"unauthorized"}  http=401
POST /api/price (key সহ) id=1 340    → {"ok":true,"id":1,"price":340}  http=200
GET  /products      → ৳320 ৳410 ৳150     ← পুরোনো, পেছনে নতুন তৈরি
GET  /products      → ৳340 ৳410 ৳150
GET  /products/1    → ৳320               ← পুরোনো
GET  /products/1    → ৳340

server log:
[db] UPDATE products SET price=340 WHERE id=1
[db #26] SELECT products 314ms
[db #29] SELECT product 1 215ms

দাম বদলের পর প্রথম অনুরোধ পুরোনো ৩২০ দেখল, আর ঠিক তখনই পেছনে SELECT products চলল। পরের অনুরোধ ৩৪০. পণ্যের পাতাও নতুন হলো, কারণ getProduct-এর গায়েও products ট্যাগ ছিল। একটি ট্যাগ অনেক জমাকে একসাথে ধরতে পারে, আর একটি জমায় একাধিক ট্যাগ থাকতে পারে। নিচে ঘটনাটি ধাপে ধাপে দেখুন।

1POST /api/price   (key নেই)2POST /api/price   {id:1, price:340}3  db.setPrice(1, 340)4  revalidateTag("products", "max")5GET /products     ক্রেতা ক6GET /products     ক্রেতা খ

নিচের মডেলে একই ঘটনা, সঙ্গে updateTag-এর তুলনা। এটি শেখানোর মডেল, Next.js-এর ভেতরের কোড নয়।

// শেখানোর মডেল: Next.js-এর tag-cache-এর সরল রূপ, আসল কোড নয়
const db = { price: 320 };
let dbHits = 0;
const store = new Map();                        // key -> { value, tags, stale }
function cached(key, tags, load) {
  const e = store.get(key);
  if (e && !e.stale) return { v: e.value, how: 'HIT' };
  if (e) {                                      // পুরোনোটা এখনই, নতুনটা পেছনে
    queueMicrotask(() => { dbHits++; store.set(key, { value: load(), tags, stale: false }); });
    return { v: e.value, how: 'STALE' };
  }
  dbHits++;
  const value = load();
  store.set(key, { value, tags, stale: false });
  return { v: value, how: 'MISS' };
}
const revalidateTag = (tag) => {                // 'max': শুধু stale চিহ্ন
  for (const e of store.values()) if (e.tags.includes(tag)) e.stale = true;
};
const updateTag = (tag) => {                    // সঙ্গে সঙ্গে বাতিল
  for (const [k, e] of store) if (e.tags.includes(tag)) store.delete(k);
};
const getProducts = () => cached('getProducts', ['products'], () => db.price);
async function visit(label) {
  const r = getProducts();
  console.log(`${label}  ${r.how.padEnd(5)} price=${r.v}  dbHits=${dbHits}`);
  await null;                                   // পেছনের কাজ শেষ হতে দিন
}
(async () => {
  await visit('visit 1'); await visit('visit 2');
  db.price = 340; revalidateTag('products'); console.log('-- price 340, revalidateTag');
  await visit('visit 3'); await visit('visit 4');
  db.price = 360; updateTag('products'); console.log('-- price 360, updateTag');
  await visit('visit 5'); await visit('visit 6');
})();

updateTag বাস্তবে কেমন দেখায়, তা form জমা দেওয়ার Server Action-এ: দোকানি দাম বদলে "সেভ" চাপলেন, তারপর নিজের পাতায় ফিরে গেলেন। তিনি পুরোনো দাম দেখলে ভাববেন সেভ হয়নি। এই কারণেই এখানে updateTag. Server Action কীভাবে লিখতে হয় আর তাকে কীভাবে সুরক্ষিত রাখতে হয়, তা পর্ব ৫৪-তে (Server Action).

৬ · অনুরোধ-নির্ভর API: cookies(), headers(), searchParams

কিছু তথ্য build-এর সময় জানা সম্ভবই নয়: কে লগইন করেছেন (cookie), কোন ভাষা চান (header), কোন ফিল্টার বেছেছেন (URL-এর ? অংশ)। এগুলো পড়ার API-কে Next.js-এর docs বলে runtime API বা request-time API: runtime API. Next.js 15 থেকে এগুলো async: await cookies(), await headers(), আর page-এর params ও searchParams একটি Promise.

আগের মডেলে একটি cookies() ডাকলেই পুরো route dynamic হয়ে যেত। Cache Components-এ নিয়ম আরও সূক্ষ্ম: যে component এগুলো পড়ে, শুধু সেটিকে Suspense-এ রাখতে হয়। না রাখলে কী হয়, দেখুন:

import { cookies } from "next/headers";

export default async function AccountBad() {
  const name = (await cookies()).get("name")?.value ?? "অতিথি";
  return <main><h1>আমার অ্যাকাউন্ট</h1><p>স্বাগতম, {name}</p></main>;
}

সত্যিকারের run · ~/bazarghar$ npx next build · Next.js 16.4.4 · build ব্যর্থ

Error: Route "/account-bad": Next.js encountered uncached or runtime data during prerendering.

`fetch(...)`, `cookies()`, `headers()`, `params`, `searchParams`, or `connection()` accessed outside of `<Suspense>` prevents the route from being prerendered, blocking the page load and leading to a slower user experience.

Ways to fix this:
  - [stream] Provide a placeholder with `<Suspense fallback={...}>` around the data access
  - [cache] For uncached data (`fetch`, database calls): cache the access with `"use cache"` (does not apply to `connection()`)
  - [block] Set `export const instant = false` to allow a blocking route
…
Export encountered an error on /account-bad/page: /account-bad, exiting the build.

Error নিজেই তিনটি পথ বলে দিচ্ছে। সবচেয়ে ভালো প্রথমটি: অনুরোধ-নির্ভর অংশটুকু আলাদা component-এ নিয়ে Suspense-এ রাখা। তাহলে শিরোনামসহ বাকি পাতা static shell-এ থাকে:

export default function AccountPage() {
  return (
    <main>
      <h1>আমার অ্যাকাউন্ট</h1>
      <Suspense fallback={<p>…</p>}>
        <Greeting />
      </Suspense>
    </main>
  );
}
async function Greeting() {
  const name = (await cookies()).get("name")?.value ?? "অতিথি";
  return <p>স্বাগতম, {name}</p>;
}

এবার build সফল, আর route table-এ ◐ /account. Cookie পাঠিয়ে আর না পাঠিয়ে দুবার খোলা হলো; HTML-এ আসল লেখা ছিল স্বাগতম, Rahima আর স্বাগতম, অতিথি. তৃতীয় পথ instant = false জেনেশুনে পুরো পাতাকে অপেক্ষা করতে দেয়; build-এ সেই route পায় ƒ চিহ্ন। এর খরচ অংশ ৭-এ মাপা হয়েছে।

৭ · Streaming: loading.js আর <Suspense>

পণ্যের পাতায় রিভিউ সবচেয়ে ধীর, ১,২০০ ms. সবকিছু রিভিউর জন্য আটকে রাখলে ক্রেতা ১.২ সেকেন্ড সাদা পর্দা দেখবেন। Streaming-এ server দ্রুত অংশটুকু আগে পাঠায়, ধীর অংশের জায়গায় একটি fallback রাখে, আর পরে একই HTTP উত্তরে বাকিটা পাঠায়। উত্তরটি একটিই, শুধু কয়েক টুকরোয় আসে। HTTP/1.1-এ এটি হয় chunked transfer encoding দিয়ে; আমাদের প্রতিটি উত্তরে header ছিল transfer-encoding: chunked.

Next.js-এ দুইভাবে Suspense বসানো যায়। loading.js (বা loading.tsx) ফাইল রাখলে Next.js পুরো page-কে নিজে থেকে একটি Suspense-এ মুড়ে দেয়। আর <Suspense> নিজে বসালে আপনি ঠিক করেন কোন ছোট অংশ অপেক্ষা করবে। বাজারঘরের পণ্যের পাতায় দুটিই আছে:

export async function generateStaticParams() {
  return [{ id: "1" }];
}
export default async function ProductPage({ params }: PageProps<"/products/[id]">) {
  const { id } = await params;
  const product = await getProduct(Number(id));     // "use cache"
  if (!product) notFound();
  return (
    <main>
      <h1>{product.name}</h1>
      <p>দাম: ৳{product.price}</p>
      <Suspense fallback={<p>রিভিউ লোড হচ্ছে…</p>}>
        <Reviews id={product.id} />
      </Suspense>
    </main>
  );
}
async function Reviews({ id }: { id: number }) {
  await connection();
  const reviews = await db.getReviews(id);          // ১২০০ ms, cache নেই
  return <ul>{reviews.map((r) => <li key={r}>{r}</li>)}</ul>;
}

এবার curl দিয়ে মাপা হলো। time_starttransfer হলো প্রথম byte আসার সময় (TTFB), time_total পুরো উত্তর।

সত্যিকারের run · curl 8.18, Next.js 16.4.4 next start · একটি local কম্পিউটারে একবার

$ curl -s -o p.html -w "%{http_code} ttfb=%{time_starttransfer}s total=%{time_total}s %{size_download}B\n" http://127.0.0.1:3753/products
200 ttfb=0.033535s total=0.474951s 14598B
$ curl … http://127.0.0.1:3753/products/1
200 ttfb=0.017985s total=1.251362s 16169B
$ curl … http://127.0.0.1:3753/blocking
200 ttfb=0.008724s total=1.425964s 11730B

শেষ লাইনটি অবাক করার মতো। /blocking পাতা Suspense ছাড়া রিভিউর জন্য অপেক্ষা করে, তবু TTFB মাত্র ৯ ms! কারণ Next.js status আর header আগেই পাঠিয়ে দেয়। তাই TTFB একা বিভ্রান্ত করতে পারে। আসল প্রশ্ন হলো, দেখার মতো HTML কখন এলো? সেটি মাপতে একটি ছোট Node script প্রতিটি টুকরো কখন এলো আর তাতে কী লেখা ছিল তা ছাপল:

সত্যিকারের run · Node.js 24-এর fetch দিয়ে প্রতিটি টুকরোর সময় · একটি local কম্পিউটারে একবার · লেখা ছোট করা

/products/1   (Suspense দিয়ে stream)
chunk 1  +41ms    1684B  <h1>সরিষার তেল ১ লিটার <p>দাম: ৳ … <template>
chunk 2  +45ms    6738B
chunk 3  +47ms    6367B
chunk 4  +1255ms   306B
chunk 6  +1256ms   987B  <li>খাঁটি ঝাঁঝ <li>সময়মতো পেয়েছি
done  1258ms

/blocking     (instant = false, Suspense নেই)
chunk 1  +1243ms  1371B  <h1>সরিষার তেল ১ লিটার <li>খাঁটি ঝাঁঝ <li>সময়মতো পেয়েছি
chunk 2  +1243ms 10345B
done  1246ms

পুরো পাতার সময় প্রায় একই, কারণ ১,২০০ ms-এর রিভিউ এড়ানো যায়নি। কিন্তু ক্রেতা নাম আর দাম দেখলেন ৪১ ms-এ, ১,২৪৩ ms-এ নয়, অর্থাৎ প্রায় ৩০ গুণ আগে। Streaming মোট কাজ কমায় না, অপেক্ষার অনুভূতি আর প্রথম দেখার সময় কমায়।

Browser-এ টুকরোগুলো জোড়া লাগে কীভাবে? প্রথম টুকরোতে fallback-এর জায়গায় একটি চিহ্ন থাকে। পরের টুকরোতে আসল রিভিউ একটি লুকানো div-এ আসে, সঙ্গে একটি ছোট script, যা দুটি জায়গা বদলে দেয়। নিচে আসল HTML থেকে নেওয়া অংশগুলো ধাপে ধাপে:

GET /products/1 HTTP/1.1
server: cached shell আছে, রিভিউর query শুরু
[db] SELECT reviews 1 …

<h1>সরিষার তেল ১ লিটার</h1><p>দাম: ৳<!-- -->320</p>
<!--$?--><template id="B:0"></template>
<p>রিভিউ লোড হচ্ছে…</p><!--/$-->

<script src="/_next/static/chunks/…">
self.__next_f.push([1, "…"])
← RSC payload: component গাছের তথ্য

<div hidden id="S:0"><ul><li>খাঁটি ঝাঁঝ</li>
<li>সময়মতো পেয়েছি</li></ul></div>

$RC("B:0","S:0")
B:0-এর fallback সরে, S:0-এর রিভিউ বসে
done 1258ms · মোট 16169 B

নিচের live React ব্লকে একই ধারণা browser-এর ভেতরে দেখুন। এটি শেখানোর মডেল: এখানে server নেই, একটি Promise ৮০০ ms পরে রিভিউ দেয়, আর React-এর use() সেই Promise-এর জন্য Suspense-কে অপেক্ষা করায়।

<div id="root"></div>
<script src="../course-kit/vendor/react-lab.js"></script>
<script type="text/jsx">
const t0 = performance.now();
const at = () => Math.round((performance.now() - t0) / 100) * 100;
// ধীর ডেটাবেসের নকল: ৮০০ ms পরে রিভিউ আসে
const reviewsP = new Promise((ok) =>
  setTimeout(() => ok(['খাঁটি ঝাঁঝ', 'সময়মতো পেয়েছি']), 800));

function Reviews() {
  const list = use(reviewsP);          // তৈরি না হলে Suspense অপেক্ষা করে
  console.log(`reviews shown ~${at()} ms`);
  return <ul>{list.map((r) => <li key={r}>{r}</li>)}</ul>;
}
function ProductPage() {
  useEffect(() => console.log(`shell shown ~${at()} ms`), []);
  return (
    <main>
      <h1>সরিষার তেল ১ লিটার</h1>
      <p>দাম: ৳320</p>
      <Suspense fallback={<p>রিভিউ লোড হচ্ছে…</p>}>
        <Reviews />
      </Suspense>
    </main>
  );
}
createRoot(document.getElementById('root')).render(<ProductPage />);
</script>

৮ · কিছু ভাঙলে: error.js

ডেটাবেস ধীর হতে পারে, আবার ভেঙেও যেতে পারে। পরীক্ষার জন্য পণ্য ৩-এর রিভিউ আনার পর ইচ্ছা করে error ছোড়া হলো: throw new Error("reviews table timeout"). Route-এর ফোল্ডারে একটি error.js ফাইল রাখলে Next.js সেই অংশকে একটি error boundary-তে মুড়ে দেয়। এটি অবশ্যই Client Component, কারণ "আবার চেষ্টা" বোতাম browser-এ চলে।

"use client";
import { useEffect } from "react";

export default function Error({ error, retry }: { error: unknown; retry: () => void }) {
  useEffect(() => { console.error(error); }, [error]);
  const digest = error instanceof Error ? (error as Error & { digest?: string }).digest : undefined;
  return (
    <div role="alert">
      <p>দুঃখিত, এই অংশটি এখন আনা গেল না।</p>
      {digest && <small>রেফারেন্স: {digest}</small>}
      <button onClick={() => retry()}>আবার চেষ্টা করুন</button>
    </div>
  );
}

সত্যিকারের run · Next.js 16.4.4 next start · GET /products/3 · server log (path ছোট করা) আর browser-এ যাওয়া HTML-এর অংশ

[db #5] SELECT product 3 213ms
[db #6] SELECT reviews 3 1210ms
⨯ Error: reviews table timeout
    at k (~/bazarghar/.next/server/chunks/ssr/…js:1:1106) {
  digest: '1751822584'
}

status 200   done 1464ms
… $RX("B:2","1751822584") …
… self.__next_f.push([1,"27:E{\"digest\":\"1751822584\"}\n"]) …

তিনটি জিনিস শেখার আছে। এক: browser পেয়েছে শুধু digest 1751822584; "reviews table timeout" লেখাটি HTML-এ একবারও নেই (grep -c timeout দিল 0). Production-এ Server Component-এর error-এর আসল বার্তা লুকানো থাকে, যাতে টেবিলের নাম বা গোপন তথ্য বাইরে না যায়। Log-এ digest দিয়ে খুঁজে আসল কারণ পাওয়া যায়; পর্ব ২৮-এ (Error handling) Express-এ একই নীতি দেখেছেন। দুই: status 200. Stream শুরু হলে header আগেই চলে গেছে, পরে আর ৫০০ পাঠানো যায় না। তাই monitoring শুধু status code দেখে চললে এই error ধরা পড়বে না; server log বা error-reporting-ও দেখতে হবে। তিন: ভাঙন শুধু সেই segment-এ আটকে থাকে, nav bar আর বাকি layout ঠিকঠাক থাকে।

পণ্য না পেলে আলাদা পথ: notFound() ডাকলে not-found.js দেখায়। "পণ্য নেই" কোনো error নয়, স্বাভাবিক উত্তর। দুটিকে আলাদা রাখুন।

৯ · Browser-এ fetch: TanStack Query এখনো কোথায় মানায়

Server Component আসার পর browser থেকে fetch করার দরকার অনেক কমেছে। তবু কিছু কাজ browser-এরই: কয়েক সেকেন্ড পরপর স্টক দেখা (polling), infinite scroll, ব্যবহারকারী টাইপ করার সাথে সাথে খোঁজা, বা optimistic update. এসব জায়গায় পর্ব ১৯-এর (Server state — TanStack Query) TanStack Query এখনো সবচেয়ে কাজের। বাজারঘরের পণ্যের পাতায় স্টক প্রতি ১০ সেকেন্ডে browser থেকে নতুন করা হয়:

"use client";
import { useQuery } from "@tanstack/react-query";

// browser থেকে প্রতি ১০ সেকেন্ডে স্টক: এখানে TanStack Query এখনো মানানসই
export default function LiveStock({ id }: { id: number }) {
  const { data, isPending } = useQuery({
    queryKey: ["stock", id],
    queryFn: () => fetch(`/api/stock/${id}`).then((r) => r.json()),
    refetchInterval: 10_000,
  });
  return <p>স্টক: {isPending ? "…" : `${data.stock}টি`}</p>;
}

এই component @tanstack/react-query 5.105.2-সহ build-এ সফলভাবে compile হয়েছে, আর server-এ তৈরি HTML-এ এর জায়গায় "স্টক: …" ছিল, কারণ প্রথম ডেটা browser-এ আসে। এখানে browser-এর আচরণ চালিয়ে দেখানো হয়নি; পর্ব ১৯-এ সেটি বিস্তারিত চালানো আছে।

১০ · AI-এর যুগে: data fetching আর cache-এর কোড যাচাই

Next.js-এর cache নিয়ে AI-এর ভুল খুব বেশি, কারণ তার শেখার ডেটায় তিনটি আলাদা যুগের কোড মেশানো: getServerSideProps-এর pages router, App Router-এর শুরুর "সব fetch cache" যুগ, আর এখনকার "use cache". ফলে এমন কোড আসে যা চলে, কিন্তু আপনার version-এ ভুল আচরণ করে।

AI-এর কোড হাতে পেলে যাচাইয়ের চেকলিস্ট

• package.json-এ Next.js-এর version দেখে সেই version-এর docs পড়েছি; প্রকল্পের node_modules/next/dist/docs-এও docs থাকে
• next build চালিয়ে route table-এ প্রতিটি পাতার চিহ্ন (○, ◐, ƒ) প্রত্যাশামতো কি না দেখেছি
• ডেটাবেস-স্তরে একটি log রেখে গুনেছি, প্রতিটি অনুরোধে কয়টি query যায়
• দাম বদলে দেখেছি পরের কোন অনুরোধে নতুন দাম আসে
• দুটি আলাদা cookie দিয়ে পাতা খুলে নিশ্চিত হয়েছি একজনের ডেটা অন্যজন দেখছেন না
• Cache বদলানোর Route handler-এ অনুমতি আর ইনপুট যাচাই আছে; কোনো secret client-এর কোডে নেই
• AI যে package বা option দিয়েছে তা npm আর docs-এ সত্যিই আছে কি না মিলিয়েছি