Why I Put 18 Post-Build Audit Scripts in Front of a Static Next.js Site
Last week I put together Stand Out Roblox Wiki ahead of a game launch. On paper, it is a straightforward content site: 48 stand pages, drop-rate tables, codes, and a few guides. Normally I would wire up a next build, pu
Last week I put together Stand Out Roblox Wiki ahead of a game launch. On paper, it is a straightforward content site: 48 stand pages, drop-rate tables, codes, and a few guides.
Normally I would wire up a next build, push to Cloudflare Pages, and call it a day. The problem with wikisβespecially when you are cross-checking stats against a fast-moving Trello board and updating pages three times a nightβis that small mistakes slip through quietly. A renamed slug leaves an orphan page. A hardcoded stat drifts out of sync with the JSON data. An external thumbnail returns 404 two days later.
Instead of relying on manual spot-checks, I ended up gating the build with a pipeline of small Node scripts. Here is what actually broke along the way, and why those scripts stayed.
1. output: 'export' has a silent trap with headers
I went with Next.js 16 (output: 'export' + trailingSlash: true) because game launch traffic spikes are spiky and predictable: everyone hits the codes and tier list pages at the exact same hour. Serving flat HTML from a CDN edge beats paying for or babysitting SSR cold starts.
One thing that tripped me up early: in Next.js, adding async headers() inside next.config.ts does nothing when output: 'export' is enabled. It does not throw an error or warn you at build timeβit simply skips generating any host header config.
If you host on Cloudflare Pages or Vercel, those cache and security headers have to live in public/_headers (or vercel.json), not in Next's config. I left a loud comment in next.config.ts just so I wouldn't forget next time.
2. Aliasing out the default Next.js polyfill bundle
By default, Next.js bundles polyfill-module even when your browserslist only targets modern evergreen browsers. On a text-and-table heavy site, shipping extra kilobytes of legacy JS polyfills to Chrome/Safari users makes no sense.
In next.config.ts, I aliased it out for both Turbopack and Webpack:
const nextConfig: NextConfig = {
output: 'export',
images: { unoptimized: true },
trailingSlash: true,
turbopack: {
resolveAlias: {
'next/dist/build/polyfills/polyfill-module': './src/lib/empty-polyfill.js',
'../build/polyfills/polyfill-module': './src/lib/empty-polyfill.js',
},
},
webpack: (config) => {
config.resolve.alias = config.resolve.alias || {};
config.resolve.alias['next/dist/build/polyfills/polyfill-module'] = path.resolve(
__dirname,
'src/lib/empty-polyfill.js'
);
return config;
},
};
To make sure a future dependency update doesn't sneak polyfills or bloated CSS back in, postbuild runs audit-browserslist-polyfills.mjs and audit-css-budget.mjs against the generated out/ directory.
3. Static does not mean "read-only"
A common reason people reach for a backend on game wikis is interactive tools. In practice, things like the Arrow Odds & Pity Calculator don't need a database or API route at all. All the drop-rate math runs client-side on top of the exact same JSON dataset that builds the static pages, so the numbers never disagree with the rest of the wiki.
4. Treating postbuild like a strict CI gate
Here is what scripts in package.json actually looks like right now:
{
"build": "node scripts/gen-content-dates.mjs && node scripts/gen-search-index.mjs && node scripts/optimize-assets.mjs && node scripts/optimize-media.mjs && node scripts/audit-data.mjs && node scripts/audit-trend-coverage.mjs && next build",
"postbuild": "node scripts/strip-legacy.mjs && node scripts/audit-hero.mjs && node scripts/audit-nav.mjs && node scripts/audit-links.mjs && node scripts/audit-canonicals.mjs && node scripts/audit-thin-content.mjs && node scripts/audit-content-integrity.mjs && node scripts/audit-content-voice.mjs && node scripts/audit-trust-copy.mjs && node scripts/audit-ui-integrity.mjs && node scripts/audit-orphans.mjs && node scripts/audit-events.mjs && node scripts/audit-updates.mjs && node scripts/audit-header-footer.mjs && node scripts/audit-css-budget.mjs && node scripts/audit-browserslist-polyfills.mjs && node scripts/audit-language.mjs && node scripts/audit-site.mjs"
}
Looks excessive at first glance, but each script is 50β120 lines of plain Node reading files in out/ and exiting with code 1 if something looks wrong:
-
audit-data.mjs&optimize-media.mjsrun beforenext buildso every external video thumbnail is downloaded/converted locally (no broken remote embeds) and JSON schemas pass validation before pages compile. -
audit-links.mjs&audit-orphans.mjscrawl the exported HTML inout/to verify zero internal 404s and make sure every route has incoming internal links. -
audit-canonicals.mjschecks that every static HTML file has a trailing-slash canonical tag matching its real output path. -
audit-language.mjscatches stray non-English characters if a copy-paste edit accidentally leaks into aen_USpage.
Running all 18 postbuild checks locally takes about 3 seconds on an exported folder. Comparing that to finding out a week later that three pages had broken canonicals or missing thumbnails, it has already paid for itself.
Curious how other people handle static site QAβdo you keep checks as small vanilla Node scripts like this, or rely on Playwright/broken-link-checker in GitHub Actions?
Originally published by Dev.to AI. Aggregated on AIWithGhost for educational purposes β full credit and traffic to the original publisher.