{"slug":"addyosmani-best-practices","name":"best-practices","description":"Apply modern web development best practices for security, compatibility, and code quality. Use when asked to \"apply best practices\", \"security audit\", \"modernize code\", \"code quality review\", or \"check for vulnerabilities\".","long_description":"---\nname: best-practices\ndescription: Apply modern web development best practices for security, compatibility, and code quality. Use when asked to \"apply best practices\", \"security audit\", \"modernize code\", \"code quality review\", or \"check for vulnerabilities\".\nlicense: MIT\nmetadata:\n author: web-quality-skills\n version: \"2.0\"\n---\n\n# Best practices\n\nModern web development standards based on Lighthouse best practices audits. Covers security, browser compatibility, and code quality patterns.\n\n## Evidence-led audit workflow\n\nWhen a rendered page is available:\n\n1. 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.\n2. Inspect the listed console and network failures and fetch individual details only when they support a finding.\n3. Supplement runtime evidence with dependency, header, configuration, and source inspection; Lighthouse is not a complete security assessment.\n4. Fix the implicated code, re-run the same audit, and keep security findings separate from style preferences.\n\nIf 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.\n\n## Security\n\nRead [the security reference](references/SECURITY.md) 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.\n\nAt minimum:\n\n* **Use HTTPS without mixed content.** Add HSTS only after confirming every relevant subdomain supports HTTPS.\n* **Treat a strict CSP as defense in depth.** Prefer nonces or hashes and test with report-only before enforcement.\n* **Sanitize untrusted HTML and protect DOM XSS sinks.** Prefer text APIs when markup is not required.\n* **Pin and review third-party code.** Use SRI where the delivery model supports it and keep dependencies patched.\n* **Verify response headers at runtime.** Source configuration alone does not prove what the deployed page sends.\n\n## Browser compatibility\n\n### Doctype declaration\n\n```html\n\n\n\n\n\n\n\n```\n\n### Character encoding\n\n```html\n\n\n\n Page\n \n\n\n\n\n\n \n Page\n\n```\n\n### Viewport meta tag\n\n```html\n\n\n Page\n\n\n\n\n \n \n Page\n\n```\n\n### Feature detection\n\n```javascript\n// ❌ Browser detection (brittle)\nif (navigator.userAgent.includes('Chrome')) {\n // Chrome-specific code\n}\n\n// ✅ Feature detection\nif ('IntersectionObserver' in window) {\n // Use IntersectionObserver\n} else {\n // Fallback\n}\n\n// ✅ Using @supports in CSS\n@supports (display: grid) {\n .container {\n display: grid;\n }\n}\n\n@supports not (display: grid) {\n .container {\n display: flex;\n }\n}\n```\n\n### Polyfills (when needed)\n\nPrefer **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.\n\nIf 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):\n\n```html\n\n```\n\n**Never load polyfills from a third-party CDN you don't control.** The `polyfill.io` service was [compromised in mid-2024](https://sansec.io/research/polyfill-supply-chain-attack) 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](https://blog.cloudflare.com/polyfill-io-now-available-on-cdnjs-reduce-your-supply-chain-risk/)) — and pin the version with [Subresource Integrity](#subresource-integrity-sri-for-third-party-scripts).\n\n---\n\n## Deprecated APIs\n\n### Avoid these\n\n```javascript\n// ❌ document.write (blocks parsing)\ndocument.write('');\n\n// ✅ Dynamic script loading\nconst script = document.createElement('script');\nscript.src = '...';\ndocument.head.appendChild(script);\n\n// ❌ Synchronous XHR (blocks main thread)\nconst xhr = new XMLHttpRequest();\nxhr.open('GET', url, false); // false = synchronous\n\n// ✅ Async fetch\nconst response = await fetch(url);\n\n// ❌ Application Cache (deprecated)\n\n\n// ✅ Service Workers\nif ('serviceWorker' in navigator) {\n navigator.serviceWorker.register('/sw.js');\n}\n```\n\n### Event listener passive\n\n```javascript\n// ❌ Non-passive touch/wheel (may block scrolling)\nelement.addEventListener('touchstart', handler);\nelement.addEventListener('wheel', handler);\n\n// ✅ Passive listeners (allows smooth scrolling)\nelement.addEventListener('touchstart', handler, { passive: true });\nelement.addEventListener('wheel', handler, { passive: true });\n\n// ✅ If you need preventDefault, be explicit\nelement.addEventListener('touchstart', handler, { passive: false });\n```\n\n---\n\n## Console & errors\n\n### No console errors\n\n```javascript\n// ❌ Errors in production\nconsole.log('Debug info'); // Remove in production\nthrow new Error('Unhandled'); // Catch all errors\n\n// ✅ Proper error handling\ntry {\n riskyOperation();\n} catch (error) {\n // Log to error tracking service\n errorTracker.captureException(error);\n // Show user-friendly message\n showErrorMessage('Something went wrong. Please try again.');\n}\n```\n\n### Error boundaries (React)\n\n```jsx\nclass ErrorBoundary extends React.Component {\n state = { hasError: false };\n \n static getDerivedStateFromError(error) {\n return { hasError: true };\n }\n \n componentDidCatch(error, info) {\n errorTracker.captureException(error, { extra: info });\n }\n \n render() {\n if (this.state.hasError) {\n return ;\n }\n return this.props.children;\n }\n}\n\n// Usage\n\n \n\n```\n\n### Global error handler\n\n```javascript\n// Catch unhandled errors\nwindow.addEventListener('error', (event) => {\n errorTracker.captureException(event.error);\n});\n\n// Catch unhandled promise rejections\nwindow.addEventListener('unhandledrejection', (event) => {\n errorTracker.captureException(event.reason);\n});\n```\n\n---\n\n## Source maps\n\n### Production configuration\n\n```javascript\n// ❌ Source maps exposed in production\n// webpack.config.js\nmodule.exports = {\n devtool: 'source-map', // Exposes source code\n};\n\n// ✅ Hidden source maps (uploaded to error tracker)\nmodule.exports = {\n devtool: 'hidden-source-map',\n};\n\n// ✅ Or no source maps in production\nmodule.exports = {\n devtool: process.env.NODE_ENV === 'production' ? false : 'source-map',\n};\n```\n\n**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.\n\nFor Vite, prefer `sourcemap: 'hidden'` over `'true'` so the `//# sourceMappingURL=` comment isn't emitted into the bundle.\n\n---\n\n## Performance best practices\n\n### Avoid blocking patterns\n\n```javascript\n// ❌ Blocking script\n\n\n// ✅ Deferred script\n\n\n// ❌ Blocking CSS import\n@import url('other-styles.css');\n\n// ✅ Link tags (parallel loading)\n\n\n```\n\n### Efficient event handlers\n\n```javascript\n// ❌ Handler on every element\nitems.forEach(item => {\n item.addEventListener('click', handleClick);\n});\n\n// ✅ Event delegation\ncontainer.addEventListener('click', (e) => {\n if (e.target.matches('.item')) {\n handleClick(e);\n }\n});\n```\n\n### Memory management\n\n```javascript\n// ❌ Memory leak (never removed)\nconst handler = () => { /* ... */ };\nwindow.addEventListener('resize', handler);\n\n// ✅ Cleanup when done\nconst handler = () => { /* ... */ };\nwindow.addEventListener('resize', handler);\n\n// Later, when component unmounts:\nwindow.removeEventListener('resize', handler);\n\n// ✅ Using AbortController\nconst controller = new AbortController();\nwindow.addEventListener('resize', handler, { signal: controller.signal });\n\n// Cleanup:\ncontroller.abort();\n```\n\n---\n\n## Code quality\n\n### Valid HTML\n\n```html\n\n
\n
\n\n
    \n
    Item
    \n
\n\n \n\n\n
\n
\n\n
    \n
  • Item
    • \n
\n\nClick\n```\n\n### Semantic HTML\n\n```html\n\n
\n
\n
Home
\n
\n
\n
\n
\n
Headline
\n
\n
\n\n\n
\n \n
\n
\n
\n

Headline

\n
\n
\n```\n\n### Image aspect ratios\n\n```html\n\n\n\n\n\n\n\n\n\n\n```\n\n---\n\n## Permissions & privacy\n\n### Request permissions properly\n\n```javascript\n// ❌ Request on page load (bad UX, often denied)\nnavigator.geolocation.getCurrentPosition(success, error);\n\n// ✅ Request in context, after user action\nfindNearbyButton.addEventListener('click', async () => {\n // Explain why you need it\n if (await showPermissionExplanation()) {\n navigator.geolocation.getCurrentPosition(success, error);\n }\n});\n```\n\n### Permissions policy\n\n```html\n\n\n\n\n\n```\n\n---\n\n## Audit checklist\n\n### Security (critical)\n- [ ] HTTPS enabled, no mixed content\n- [ ] No vulnerable dependencies (`npm audit`)\n- [ ] CSP headers configured (with `frame-ancestors`, `base-uri`, `form-action`)\n- [ ] `require-trusted-types-for 'script'` enforced (or report-only during rollout)\n- [ ] Third-party `