Dev.to AI πŸ€– Ai πŸ‘ 0 πŸ“– 4 min read

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.mjs run before next build so 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.mjs crawl the exported HTML in out/ to verify zero internal 404s and make sure every route has incoming internal links.
  • audit-canonicals.mjs checks that every static HTML file has a trailing-slash canonical tag matching its real output path.
  • audit-language.mjs catches stray non-English characters if a copy-paste edit accidentally leaks into a en_US page.

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?

πŸ“° Read the original article on Dev.to AI

Originally published by Dev.to AI. Aggregated on AIWithGhost for educational purposes β€” full credit and traffic to the original publisher.