Subchapter 7.132

Cache Components Suspense Dedupe

Source

lib/scanners/cache-components-suspense-dedupe.mjs

JavaScript109 lines4 KB

1// Detects the Cache Components anti-pattern where `'use cache'` doesn't dedupe across
2// separate `<Suspense>` boundaries — each boundary triggers a separate evaluation of the
3// "shared" cached function, multiplying invocations and ISR write pressure.
4//
5// Simplified single-file heuristic (cross-file segment analysis is out of scope):
6//   File contains `'use cache'` directive (or `use cache` keyword)
7//   AND file has 2+ `<Suspense ...>` boundaries
8//   AND a repeated fetch URL or function call appears in the body.
9//
10// False positives are tolerable: the support-topic body recommends a known-good remediation
11// (hoist promise to page, or move to `'use cache: remote'`) whether or not the specific call
12// site is the exact one paying the cost. The verifier abstains when the file structure
13// doesn't match the pitfall.

cache-components-suspense-dedupe.mjs on GitHub

import { lineOf } from '../util.mjs';

export const metadata = {

id: 'cache-components-suspense-dedupe',

title: "'use cache' with multiple Suspense boundaries on the same data",

severity: 'medium',

billingDimension: 'function-duration',

trafficIndependent: false,

description:

"Default `'use cache'` does not dedupe identical calls across separate `<Suspense>` boundaries on the same render. Each boundary re-invokes the cached function, multiplying function-duration cost and inflating ISR write churn when the output is large.",

fix:

"Hoist the promise to the page level (`const dataPromise = fetchData()` at the top, passed down to each Suspense child) OR move the shared fetch into a `'use cache: remote'` data-access layer so cross-request and cross-boundary dedupe applies.",

citations: [

'https://nextjs.org/docs/app/api-reference/directives/use-cache',

'https://nextjs.org/docs/app/api-reference/config/next-config-js/cacheComponents',

'https://nextjs.org/docs/app/guides/migrating-to-cache-components',

],

excludeGlobs: ['node_modules/**', '.next/**', 'dist/**', '__tests__/**', '**/*.test.*', '**/*.spec.*'],

includeGlobs: [

'**/page.{ts,tsx,js,jsx}',

'**/layout.{ts,tsx,js,jsx}',

'**/components/**/*.{tsx,jsx}',

],

};

const USE_CACHE_RE = /^[\t ]*['"]use cache['"]/m;

const SUSPENSE_TAG_RE = /<Suspense\b/g;

const FETCH_LITERAL_RE = /fetch\s*\(\s*(['"`])([^'"`]{6,200})\1/g;

// Helper function calls that look like data-fetchers (lowercase camel, no JSX/HTML noise).

export function scan({ files }) {

const out = [];

for (const { path, content } of files) {

if (!USE_CACHE_RE.test(content)) continue;

const suspenseCount = countMatches(content, SUSPENSE_TAG_RE);

if (suspenseCount < 2) continue;

const repeated = findRepeated(content);

if (repeated.length === 0) continue;

// Anchor the finding to the first repeated call site so the customer

// can locate the duplicate quickly.

const first = repeated[0];

out.push({

pattern: metadata.id,

file: path,

line: lineOf(content, first.firstIdx),

evidence: first.kind === 'fetch'

? `fetch("${truncate(first.token, 60)}") called ${first.count}× across Suspense boundaries`

: `${first.token}() called ${first.count}× across Suspense boundaries`,

trafficIndependent: metadata.trafficIndependent,

subtype: first.kind === 'fetch' ? 'fetch-literal' : 'helper-call',

});

}

return out;

}

function countMatches(content, re) {

re.lastIndex = 0;

let n = 0;

while (re.exec(content) !== null) n++;

return n;

}

function findRepeated(content) {

const tokens = new Map(); // token -> { kind, count, firstIdx }

let m;

FETCH_LITERAL_RE.lastIndex = 0;

while ((m = FETCH_LITERAL_RE.exec(content)) !== null) {

record(tokens, m[2], 'fetch', m.index);

}

HELPER_CALL_RE.lastIndex = 0;

while ((m = HELPER_CALL_RE.exec(content)) !== null) {

const name = m[0].replace(/\s*\($/, '').trim();

record(tokens, name, 'helper', m.index);

}

return [...tokens.values()]

.filter((t) => t.count >= 2)

.sort((a, b) => b.count - a.count);

}

function record(map, token, kind, idx) {

if (!token) return;

if (!map.has(token)) {

map.set(token, { token, kind, count: 0, firstIdx: idx });

}

map.get(token).count++;

}

function truncate(s, n) {

if (s.length <= n) return s;

return s.slice(0, n - 1) + '…';

}