Why Portfolio Rewrites Break Static Assets (and How to Prevent It)

Why Portfolio Rewrites Break Static Assets (and How to Prevent It)

Front-end rewrites often ship with perfect local previews and broken production assets. The root issue is usually path assumptions that change between environments.

Step 1: Centralize asset URL construction

export function asset(path) {
  const base = window.__ASSET_BASE__ || "/";
  return `${base.replace(/\/$/, "")}/${path.replace(/^\//, "")}`;
}

Step 2: Avoid hard-coded root-relative links in templates

const logoUrl = asset("img/logo.png");
const cssUrl = asset("css/site.css");

Step 3: Add build-time smoke checks

node scripts/check-assets.js --manifest dist/asset-manifest.json --base /portfolio/

Pitfalls to avoid

• Mixing absolute and relative asset references in one page.
• Renaming files without updating cache-busted manifest links.
• No test deployment under non-root subpaths.

Validation checklist

• Site renders correctly under root and subpath hosting.
• Manifest references match built files exactly.
• Broken asset URLs fail CI before deploy.