How can we pass a unique request ID (stored in cookies) to the backend on every API call — while still keeping the API fully cacheable and not breaking shared caching?

[abhishekmardiya]

Summary

I want to attach a unique request ID to every outbound API call made from the backend.

The challenge: getting this ID from cookies requires calling cookies(), and once cookies() is used the api becomes non-cacheable. Using use cache: private also doesn’t help, because most of these endpoints are not user-specific and should continue to stay fully share-cacheable.

So what would be the workaround — or is it even possible — to keep all APIs fully cacheable while still sending a unique ID with every request?

For Example:

import { cookies } from "next/headers";

const cookieStore = await cookies();
const deviceUniqueId = cookieStore?.get("uniqueId")?.value

await fetch(url, {
    headers: {
      'x-trace-id': deviceUniqueId
    }
  });

Additional information

No response

Example

No response

[icyJoseph]

We'll soon have updated examples (literally resolving some internal comments on my updated document)

In this case, you can refactor.

import { cookies } from "next/headers";

async function CookieSection() {
  const cookieStore = await cookies();
  const deviceUniqueId = cookieStore?.get("uniqueId")?.value
  
  const data = await fetchWithUniqueId(deviceUniqueId ?? 'no-unique-id-found');
  
  return <>SomeJSX</>
}

export default function Page() {
   return <Suspense fallback={<p>Some meaningful UI</p>}><CookieSection /></Suspense>
}

And then do:

async function fetchWithUniqueDeviceId(deviceId: string) {
  'use cache'
  const response = await fetch(url, {
      headers: {
        'x-trace-id': deviceUniqueId
      }
    });

  return response // idk what you do with this await response.text() or .json()
}

This way you can runtime cache the results of your function.

[abhishekmardiya]

@icyJoseph
Hii,

I’m using Next.js 16 and haven’t enabled cacheComponents.
Here’s my simplified code example:

// page.tsx
export default async function Page() {
  await getProperty();
  return <SomeJsx />;
}

export const getProperty = async () => {
  const headersInstance = await headers();
  const deviceInfo = await headersInstance?.get("user-agent");

  const data = await fetcher(`/api/property`, {
    tag: `property`,
    deviceInfo,
  });

  return data;
};

// lib/fetcher.ts
export const fetcher = async (
  url: string,
  cfg?: { tag?: string; deviceInfo?: object }
) => {
  await fetch(`${process.env.API_BASE_URL}${url}`, {
    method: "GET",
    headers: {
      "Content-Type": "application/json",
      ...(cfg?.deviceInfo && { deviceInfo: JSON.stringify(cfg.deviceInfo) }),
    },
    ...(cfg?.tag && { cache: "force-cache" }),
    ...(cfg?.tag && { next: { tags: [cfg.tag] } }),
  });
};

Since I’m calling headers() inside getProperty, does this make the entire function dynamic, thus disabling fetch caching, even if I’m using cache: "force-cache" and next: { tags: [...] }?

Follow-up Question
Currently, getProperty is not a server action — it’s just a normal async function used inside a server component.
If I convert it into a server action, Would this change anything in terms of caching behavior?

[icyJoseph]

The fetch cache layer is a different thing here, and since you are using force-cache, it'll MISS once and then HIT the Data Cache layer. Never mind that, the entire page has dynamic behavior as understood in v15 w/o cacheComponents, so the page is dynamic.

And converting to server functions shouldn't change the caching behavior. Fetch reqs still MISS or HIT the underlying Data Cache. There's likely some nuance I am leaving aside, or not accounting for though, which is why Cache Components is just such a better model.

[abhishekmardiya]

Thank you so much for the quick response!

I think it’s time for me to switch to cacheComponents, because without it, things aren’t working as expected, and it’s been pretty confusing since no errors are being shown. With cacheComponents, though, the error messages are much clearer and more meaningful.

Also, I have a question — do we still need to include cache: "force-cache" when using options like next: { revalidate: ... } or next: { tags: [...] }?
Or is it better to simply omit any additional cache arguments in the fetch call when the "use cache" directive is already applied above it?

[icyJoseph]

It is not forbidden, but in terms of the learning experience, the way we are thinking about this is, for new projects/code written under Cached Components, you should use the cacheLife and cacheTag right under the use cache directive scope.

This has also the benefit of not caching the entire fetch response, but the output of the function/component.

Though I should say, in some platforms using serverless, runtime caching might not work as expected, since it keeps things in memory, then when the lambda running the code is shutdown, the memory is gone with it.

[abhishekmardiya]

Thank you for the clarification.