Nicholai/nicholai-work-2026
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
nicholai-work-2026/dev/optimization-guidelines.md
Nicholai 3efb7fd43c Add documentation for development processes and optimization guidelines 
- Created CLAUDE.md to provide guidance on development commands, high-level architecture, content structure, and component relationships.
- Added dev/optimization-guidelines.md outlining performance principles and best practices for high-performance web code, inspired by McMaster-Carr's website.
- Introduced a new blog post, 'Building Your Own Tools: From VFX Artist to Developer', discussing the transition to self-hosting and AI development.
- Included a new asset, claude-nuke.png, for use in the blog post.
2025-12-12 14:23:56 -07:00

6.0 KiB
Raw Blame History

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.