DEV Community

Cover image for Why I Put 18 Post-Build Audit Scripts in Front of a Static Next.js Site
Chen Tao
Chen Tao

Posted on

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, 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;
  },
};
Enter fullscreen mode Exit fullscreen mode

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"
}
Enter fullscreen mode Exit fullscreen mode

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?

Top comments (0)