# High-Performance Web Code Guidelines ## Lessons from a 100-Year-Old Company with One of the Fastest Websites on the Internet This guide distills practical engineering principles observed from a deep inspection of McMaster-Carr’s website - a site that looks old, feels instant, and consistently outperforms modern, framework-heavy builds. None of these techniques are new. All of them are deliberate. The takeaway is simple: **perceived speed is a product of ruthless prioritization, not trendy technology**. --- ## Core Philosophy - HTML is the product. Everything else is optional. - Load what is needed, when it is needed, and never sooner. - Prevent layout shifts at all costs. - Measure everything. Assume nothing. - Optimize for real users on real devices, not benchmarks. --- ## 1. Server-Rendered HTML as the Primary Artifact ### Guideline Always server-render full HTML responses. ### Why Browsers are extremely good at parsing and rendering HTML. Shipping complete markup eliminates client-side bootstrapping delays and avoids blocking the initial render. ### Practices - Avoid client-side frameworks for initial rendering. - Return fully formed HTML from the server. - Treat JavaScript as an enhancement layer, not a prerequisite. --- ## 2. Aggressive HTML Prefetching on User Intent ### Guideline Prefetch HTML on hover or early interaction signals. ### Why By the time the user clicks, the page is already downloaded. ### Practices - Trigger HTML requests on `mouseover` or focus. - Cache prefetched responses for immediate swap-in. - Replace only the page-specific content shell, not global UI. ### Result - Page content renders before the URL bar updates. - Navigation feels instantaneous. --- ## 3. Partial Page Swaps with History API ### Guideline Update only what changes between pages. ### Why Navigation, carts, headers, and persistent UI should not be reloaded. ### Practices - Use `pushState` to manage navigation. - Replace only the dynamic content region. - Preserve application state across page transitions. --- ## 4. Multi-Layer Caching Strategy ### Guideline Cache HTML everywhere. ### Layers - CDN edge caching for pre-rendered HTML. - Proxy caches (e.g. Squid). - Browser cache via service workers. ### Practices - Inspect response headers to confirm cache hits. - Use `HIT/MISS` headers to validate effectiveness. - Serve cached HTML instantly when possible. --- ## 5. Service Workers for HTML, Not Just Assets ### Guideline Intercept and serve cached HTML using service workers. ### Why HTML caching enables near-zero-latency reloads and offline support. ### Practices - Cache primary routes via service worker. - Serve cached HTML on repeat visits. - Use this approach to power mobile and iOS applications. --- ## 6. Strategic Resource Preloading ### Guideline Tell the browser what it will need before it discovers it. ### Practices - Use `` for: - Logos - Web fonts - Critical images - Use `` for: - Image domains - Asset CDNs ### Why This collapses waterfall request chains and removes DNS lookup latency during render. --- ## 7. Critical CSS Inlined in HTML ### Guideline Inline all above-the-fold CSS directly in the document ``. ### Why External CSS blocks rendering and causes layout jank. ### Practices - Embed essential layout and typography CSS inline. - Load non-critical CSS asynchronously after initial render. - Ensure the browser has all layout rules before parsing body HTML. ### Result - No flashes - No reflows - No layout instability --- ## 8. Zero Layout Shift Image Strategy ### Guideline Always reserve image space before images load. ### Practices - Explicitly define width and height for all images. - Use fixed-size containers for background images. - Never allow images to resize content after load. ### Result - No cumulative layout shift - Stable rendering pipeline --- ## 9. Sprite-Based Image Bundling ### Guideline Minimize image requests by bundling assets into sprites. ### Why One request beats many, especially on constrained devices. ### Practices - Combine page images into a single sprite. - Use CSS background positioning to display regions. - Prefer fewer medium-sized assets over many small ones. --- ## 10. Page-Specific JavaScript Loading ### Guideline Only load JavaScript that is required for the current page. ### Why Unused JavaScript still blocks parsing, execution, and memory. ### Practices - Generate page-level dependency manifests server-side. - Include only required scripts per route. - Avoid global JavaScript bundles. ### Concept Dependency injection at the page level, not the application level. --- ## 11. JavaScript Is Secondary, Not Sacred ### Observations - Legacy libraries like YUI and jQuery are still in use. - Total JavaScript payload can be large and still feel fast. ### Why It Works - JavaScript does not block HTML rendering. - Execution is deferred until after meaningful paint. - Performance is measured and monitored constantly. ### Guideline Framework choice does not determine performance discipline does. --- ## 12. Instrument Everything ### Guideline Measure real user performance continuously. ### Practices - Use `window.performance` - Add custom performance marks. - Track Largest Contentful Paint and render milestones. ### Why You cannot optimize what you do not measure. --- ## 13. Optimize for Real Users, Not Ideal Conditions ### User Reality - Old phones - Dirty screens - Fat fingers - Poor connectivity - Zero patience ### Design Implication - Speed is usability. - Complexity is abandonment. - Friction leads to phone calls and paper workflows. --- ## Final Takeaways - Fast websites are engineered, not themed. - Old technology can outperform modern stacks when used intentionally. - HTML-first, cache-everywhere, and measure-constantly beats any framework war. - Perceived performance matters more than architectural purity. This approach is compatible with modern server-rendered frameworks and decades-old stacks alike. The difference is not tooling. The difference is discipline.