TRAC-1633: Declare a revalidate window for published API requests

[jordanarldt]

Jira: TRAC-1633

What/Why?

@makeswift/runtime tags its API responses with @@makeswift but never declares a revalidate window, so under fetchCache = 'default-cache' Next.js cached published content indefinitely and only the site.published webhook could refresh it — on hosts Makeswift cannot reach, most obviously a local dev server, content never updated at all. Requests for the published site now declare a TTL via MAKESWIFT_REVALIDATE_TARGET: 3600 in production, where the webhook is the real freshness mechanism and this is only a backstop, and 0 in development, where the webhook never arrives and the TTL is the only invalidation. Draft requests are skipped deliberately — the SDK already sets cache: 'no-store' for them, and adding revalidate alongside it makes Next.js discard both values and fall back to caching the builder's live edits indefinitely.

Testing

Verified against pnpm dev by inspecting the on-disk fetch cache:

• Development default (0) — no api.makeswift.com/v4|v5 entries are written; every request is fresh.
• With MAKESWIFT_REVALIDATE_TARGET=3600 — entries appear as revalidate: 3600, tags: ["@@makeswift"]. Previously 31536000.
• No collateral damage — BigCommerce Storefront queries stay at revalidate: 3600, since they all pass explicit fetchOptions.

To reproduce:

rm -rf .next && pnpm dev
curl -s -o /dev/null http://localhost:3000/
grep -l 'api.makeswift.com' .next/dev/cache/fetch-cache/* \
  | xargs -I{} jq -c '{revalidate, tags, url: .data.url}' {}

Proof of fix

Screen.Recording.2026-08-21.at.3.38.25.PM.mov

On Native Hosting (depends on #3183)

Screen.Recording.2026-08-21.at.3.40.10.PM.mov

Migration

None. MAKESWIFT_REVALIDATE_TARGET is optional, and the defaults preserve current behaviour on hosts that receive publish webhooks. Hosts that don't will now refresh on the TTL instead of never. No files moved.

[changeset-bot]

🦋 Changeset detected

Latest commit: da3e1f3

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@bigcommerce/catalyst-makeswift	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
catalyst	Ready	Preview	Aug 21, 2026 8:33pm

[github-actions]

Bundle Size Report

Comparing against baseline from 7c0b85d (2026-08-21).

No bundle size changes detected.

[github-actions]

Unlighthouse Performance Comparison — Vercel

Comparing PR preview deployment Unlighthouse scores vs production Unlighthouse scores.

Summary Score

Aggregate score across all categories as reported by Unlighthouse.

	Prod Desktop	Prod Mobile	Preview Desktop	Preview Mobile
Score	87	90	89	93

Category Scores

Category	Prod Desktop	Prod Mobile	Preview Desktop	Preview Mobile
Performance	66	82	66	77
Accessibility	91	91	91	92
Best Practices	100	100	100	100
SEO	89	89	100	100

Core Web Vitals

Metric	Prod Desktop	Prod Mobile	Preview Desktop	Preview Mobile
LCP	5.7 s	4.7 s	7.0 s	6.3 s
CLS	0.001	0	0.001	0
FCP	1.4 s	1.5 s	1.4 s	1.4 s
TBT	20 ms	20 ms	20 ms	30 ms
Max Potential FID	80 ms	80 ms	80 ms	80 ms
Time to Interactive	7.4 s	6.5 s	7.6 s	6.4 s

Full Unlighthouse report →