# 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 `<link rel="preload">` for:
  - Logos
  - Web fonts
  - Critical images
- Use `<link rel="dns-prefetch">` 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 `<head>`.

### 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.