Best practices
Modern web development standards based on Lighthouse best practices audits. Covers security, browser compatibility, and code quality patterns.
Evidence-led audit workflow
When a rendered page is available:
- Run a live Lighthouse Best Practices audit when that capability is available; with Chrome DevTools MCP, use
lighthouse_audit. Use navigation mode for a normal page load or snapshot mode when the current state must be preserved. - Inspect the listed console and network failures and fetch individual details only when they support a finding.
- Supplement runtime evidence with dependency, header, configuration, and source inspection; Lighthouse is not a complete security assessment.
- Fix the implicated code, re-run the same audit, and keep security findings separate from style preferences.
If live tools are unavailable, use the Lighthouse CLI plus focused dependency and header checks. Never report a high Lighthouse score as proof that the application is secure.
Security
Read the security reference when security is in scope or a live audit surfaces a related failure. It covers HTTPS/HSTS, CSP and Trusted Types, Subresource Integrity, headers, dependencies, sanitization, and cookies.
At minimum:
- Use HTTPS without mixed content. Add HSTS only after confirming every relevant subdomain supports HTTPS.
- Treat a strict CSP as defense in depth. Prefer nonces or hashes and test with report-only before enforcement.
- Sanitize untrusted HTML and protect DOM XSS sinks. Prefer text APIs when markup is not required.
- Pin and review third-party code. Use SRI where the delivery model supports it and keep dependencies patched.
- Verify response headers at runtime. Source configuration alone does not prove what the deployed page sends.
Browser compatibility
Doctype declaration
html<!-- ❌ Missing or invalid doctype --> <HTML> <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"> <!-- ✅ HTML5 doctype --> <!DOCTYPE html> <html lang="en">
Character encoding
html<!-- ❌ Missing or late charset --> <html> <head> <title>Page</title> <meta charset="UTF-8"> </head> <!-- ✅ Charset as first element in head --> <html> <head> <meta charset="UTF-8"> <title>Page</title> </head>
Viewport meta tag
html<!-- ❌ Missing viewport --> <head> <title>Page</title> </head> <!-- ✅ Responsive viewport --> <head> <meta charset="UTF-8"> <meta name="viewport" content="width=device-width, initial-scale=1"> <title>Page</title> </head>
Feature detection
javascript// ❌ Browser detection (brittle) if (navigator.userAgent.includes('Chrome')) { // Chrome-specific code } // ✅ Feature detection if ('IntersectionObserver' in window) { // Use IntersectionObserver } else { // Fallback } // ✅ Using @supports in CSS @supports (display: grid) { .container { display: grid; } } @supports not (display: grid) { .container { display: flex; } }
Polyfills (when needed)
Prefer bundling polyfills at build time (Babel/SWC + core-js, or @vitejs/plugin-legacy) targeted by your supported-browsers list. This eliminates the runtime check entirely and avoids shipping polyfill bytes to modern browsers.
If you must load a polyfill at runtime, append a script element — never use document.write (it blocks the parser and is broken in async/deferred contexts):
html<script> if (!('fetch' in window)) { const s = document.createElement('script'); s.src = '/polyfills/fetch.js'; s.defer = true; document.head.appendChild(s); } </script>
Never load polyfills from a third-party CDN you don't control. The polyfill.io service was compromised in mid-2024 in a supply-chain attack and used to serve malware to ~100k sites. Self-host, or use a vetted mirror (e.g. Cloudflare's cdnjs polyfill build) — and pin the version with Subresource Integrity.
Deprecated APIs
Avoid these
javascript// ❌ document.write (blocks parsing) document.write('<script src="..."></script>'); // ✅ Dynamic script loading const script = document.createElement('script'); script.src = '...'; document.head.appendChild(script); // ❌ Synchronous XHR (blocks main thread) const xhr = new XMLHttpRequest(); xhr.open('GET', url, false); // false = synchronous // ✅ Async fetch const response = await fetch(url); // ❌ Application Cache (deprecated) <html manifest="cache.manifest"> // ✅ Service Workers if ('serviceWorker' in navigator) { navigator.serviceWorker.register('/sw.js'); }
Event listener passive
javascript// ❌ Non-passive touch/wheel (may block scrolling) element.addEventListener('touchstart', handler); element.addEventListener('wheel', handler); // ✅ Passive listeners (allows smooth scrolling) element.addEventListener('touchstart', handler, { passive: true }); element.addEventListener('wheel', handler, { passive: true }); // ✅ If you need preventDefault, be explicit element.addEventListener('touchstart', handler, { passive: false });
Console & errors
No console errors
javascript// ❌ Errors in production console.log('Debug info'); // Remove in production throw new Error('Unhandled'); // Catch all errors // ✅ Proper error handling try { riskyOperation(); } catch (error) { // Log to error tracking service errorTracker.captureException(error); // Show user-friendly message showErrorMessage('Something went wrong. Please try again.'); }
Error boundaries (React)
jsxclass ErrorBoundary extends React.Component { state = { hasError: false }; static getDerivedStateFromError(error) { return { hasError: true }; } componentDidCatch(error, info) { errorTracker.captureException(error, { extra: info }); } render() { if (this.state.hasError) { return <FallbackUI />; } return this.props.children; } } // Usage <ErrorBoundary> <App /> </ErrorBoundary>
Global error handler
javascript// Catch unhandled errors window.addEventListener('error', (event) => { errorTracker.captureException(event.error); }); // Catch unhandled promise rejections window.addEventListener('unhandledrejection', (event) => { errorTracker.captureException(event.reason); });
Source maps
Production configuration
javascript// ❌ Source maps exposed in production // webpack.config.js module.exports = { devtool: 'source-map', // Exposes source code }; // ✅ Hidden source maps (uploaded to error tracker) module.exports = { devtool: 'hidden-source-map', }; // ✅ Or no source maps in production module.exports = { devtool: process.env.NODE_ENV === 'production' ? false : 'source-map', };
Strip sourcesContent from production maps when uploading to your error tracker. By default, bundlers embed the full original source inside the .map file — anyone who obtains the map (including via a misconfigured upload step) gets your unminified code. Configure your bundler to omit sourcesContent, or use a Sentry/Bugsnag CLI flag that does so when uploading.
For Vite, prefer sourcemap: 'hidden' over 'true' so the //# sourceMappingURL= comment isn't emitted into the bundle.
Performance best practices
Avoid blocking patterns
javascript// ❌ Blocking script <script src="heavy-library.js"></script> // ✅ Deferred script <script defer src="heavy-library.js"></script> // ❌ Blocking CSS import @import url('other-styles.css'); // ✅ Link tags (parallel loading) <link rel="stylesheet" href="styles.css"> <link rel="stylesheet" href="other-styles.css">
Efficient event handlers
javascript// ❌ Handler on every element items.forEach(item => { item.addEventListener('click', handleClick); }); // ✅ Event delegation container.addEventListener('click', (e) => { if (e.target.matches('.item')) { handleClick(e); } });
Memory management
javascript// ❌ Memory leak (never removed) const handler = () => { /* ... */ }; window.addEventListener('resize', handler); // ✅ Cleanup when done const handler = () => { /* ... */ }; window.addEventListener('resize', handler); // Later, when component unmounts: window.removeEventListener('resize', handler); // ✅ Using AbortController const controller = new AbortController(); window.addEventListener('resize', handler, { signal: controller.signal }); // Cleanup: controller.abort();
Code quality
Valid HTML
html<!-- ❌ Invalid HTML --> <div id="header"> <div id="header"> <!-- Duplicate ID --> <ul> <div>Item</div> <!-- Invalid child --> </ul> <a href="/"><button>Click</button></a> <!-- Invalid nesting --> <!-- ✅ Valid HTML --> <header id="site-header"> </header> <ul> <li>Item</li> </ul> <a href="/" class="button">Click</a>
Semantic HTML
html<!-- ❌ Non-semantic --> <div class="header"> <div class="nav"> <div class="nav-item">Home</div> </div> </div> <div class="main"> <div class="article"> <div class="title">Headline</div> </div> </div> <!-- ✅ Semantic HTML5 --> <header> <nav> <a href="/">Home</a> </nav> </header> <main> <article> <h1>Headline</h1> </article> </main>
Image aspect ratios
html<!-- ❌ Distorted images --> <img src="photo.jpg" width="300" height="100"> <!-- If actual ratio is 4:3, this squishes the image --> <!-- ✅ Preserve aspect ratio --> <img src="photo.jpg" width="300" height="225"> <!-- Actual 4:3 dimensions --> <!-- ✅ CSS object-fit for flexibility --> <img src="photo.jpg" style="width: 300px; height: 200px; object-fit: cover;">
Permissions & privacy
Request permissions properly
javascript// ❌ Request on page load (bad UX, often denied) navigator.geolocation.getCurrentPosition(success, error); // ✅ Request in context, after user action findNearbyButton.addEventListener('click', async () => { // Explain why you need it if (await showPermissionExplanation()) { navigator.geolocation.getCurrentPosition(success, error); } });
Permissions policy
html<!-- Restrict powerful features --> <meta http-equiv="Permissions-Policy" content="geolocation=(), camera=(), microphone=()"> <!-- Or allow for specific origins --> <meta http-equiv="Permissions-Policy" content="geolocation=(self 'https://maps.example.com')">
Audit checklist
Security (critical)
- HTTPS enabled, no mixed content
- No vulnerable dependencies (
npm audit) - CSP headers configured (with
frame-ancestors,base-uri,form-action) -
require-trusted-types-for 'script'enforced (or report-only during rollout) - Third-party
<script>/<link rel="stylesheet">pinned with SRI hashes - Security headers present (HSTS, X-Content-Type-Options, Referrer-Policy)
- No exposed source maps (and
sourcesContentstripped from uploaded ones)
Compatibility
- Valid HTML5 doctype
- Charset declared first in head
- Viewport meta tag present
- No deprecated APIs used
- Passive event listeners for scroll/touch
Code quality
- No console errors
- Valid HTML (no duplicate IDs)
- Semantic HTML elements used
- Proper error handling
- Memory cleanup in components
UX
- No intrusive interstitials
- Permission requests in context
- Clear error messages
- Appropriate image aspect ratios
Tools
| Tool | Purpose |
|---|---|
npm audit | Dependency vulnerabilities |
| SecurityHeaders.com | Header analysis |
| W3C Validator | HTML validation |
Live Lighthouse audit (Chrome DevTools MCP: lighthouse_audit) | Rendered Best Practices checks for agents |
| Lighthouse CLI | Best Practices audit fallback |
| Observatory | Security scan |
