Nicholai
3efb7fd43c
- 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.
243 lines
6.0 KiB
Markdown
243 lines
6.0 KiB
Markdown
# 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. |