addyosmani/web-quality-skills/best-practices

Trust tier 3
  • community
Source check pending

Checking that the SKILL.md file is still in the repository.

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

Install

npx vskill@latest install addyosmani/web-quality-skills/best-practices

SKILL.md

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:

  1. 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.
  2. Inspect the listed console and network failures and fetch individual details only when they support a finding.
  3. Supplement runtime evidence with dependency, header, configuration, and source inspection; Lighthouse is not a complete security assessment.
  4. 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)
jsx
class 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 sourcesContent stripped 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

This is the start of the file. Read the full SKILL.md on GitHub.

Security

  • Security scanPassed, 95 of 100Pattern checks on the skill's files.
  • Model reviewPassed

See the full security report

Quality evaluation

  • Task evaluationNot runNo evaluation yet. Run one in Skill Studio.

See evaluation results

Source

Popularity

Repository stars
1,910
Repository forks
169
7-day trend score
38

Stars and forks are for the whole GitHub repository, not this skill alone. Refreshed 12 May 2026, 5 months ago.

Works with

Any agent vskill installs to: 56 targets in all. These 39 have a page on this site.

  • Claude Code
  • Cursor
  • GitHub Copilot
  • Windsurf
  • Codex
  • Gemini CLI
  • Cline
  • Amp
  • Roo Code
  • Goose
  • Continue
  • Kilo Code
  • Junie
  • Trae
  • OpenHands
  • Qwen Code
  • AI Agent
  • Tabnine Chat
  • Sourcegraph Cody
  • Amazon Q
  • Firebase Genkit
  • Sweep
  • Devin
  • Phind
  • Mentat
  • Claude Desktop
  • Aider
  • GPT Pilot
  • Plandex
  • bolt.new
  • v0
  • Replit Agent
  • Anse
  • TypingMind
  • BetterChatGPT
  • LibreChat
  • Warp AI
  • Pieces
  • Fig AI
Embed badge
vskill VERIFIED badge
[![vskill VERIFIED](https://verified-skill.com/api/v1/skills/addyosmani/web-quality-skills/best-practices/badge)](https://verified-skill.com/skills/addyosmani/web-quality-skills/best-practices)

Something wrong with this skill or its page? Tell us.