Performance Rules

Rules for validating performance best practices.

css-analysis

Analyzes stylesheets for performance issues.

Checks

Not too many external stylesheets (>5)
Not too much inline CSS (>50KB)
Detects render-blocking CSS
Too many inline styles (>50 elements)

Examples

Info:

<link rel="stylesheet" href="bootstrap.css">
<link rel="stylesheet" href="theme.css">
<link rel="stylesheet" href="components.css">
<link rel="stylesheet" href="utilities.css">
<link rel="stylesheet" href="custom.css">
<link rel="stylesheet" href="overrides.css">
<!-- Info: Many external stylesheets (6). Consider bundling. -->

Info:

<style>
  /* 60KB of inline CSS */
</style>
<!-- Info: Large inline CSS (60KB). Consider external stylesheet. -->

Info:

<div style="color: red">
<span style="font-size: 14px">
<!-- ... 50+ elements with inline styles -->
<!-- Info: Many elements with inline styles (55). Use CSS classes. -->

Configuration

rules: {
  'css-analysis': {
    severity: 'info',
  },
}

js-analysis

Analyzes scripts for performance issues.

Checks

Not too many scripts (>15)
Render-blocking scripts in head
Scripts without async/defer
Third-party script count (>5)
Large inline scripts (>30KB)

Examples

Info:

<head>
  <script src="analytics.js"></script>
  <script src="app.js"></script>
  <!-- Info: Scripts in head without async/defer may block rendering -->
</head>

Pass:

<head>
  <script src="analytics.js" async></script>
  <script src="app.js" defer></script>
</head>

Info:

<!-- 20 script tags -->
<!-- Info: Many scripts (20). Consider bundling. -->

Info:

<script src="https://cdn1.com/lib.js"></script>
<script src="https://cdn2.com/lib.js"></script>
<script src="https://cdn3.com/lib.js"></script>
<script src="https://cdn4.com/lib.js"></script>
<script src="https://cdn5.com/lib.js"></script>
<script src="https://cdn6.com/lib.js"></script>
<!-- Info: Many third-party scripts (6). Monitor performance. -->

Configuration

rules: {
  'js-analysis': {
    severity: 'info',
  },
}

resource-hints

Validates preload/prefetch/preconnect usage.

Checks

Preconnect for third-party origins
Preload for critical fonts/CSS
DNS-prefetch for external domains

Examples

Info:

<script src="https://cdn.example.com/lib.js"></script>
<!-- Info: Consider preconnect for https://cdn.example.com -->

Pass:

<head>
  <!-- Preconnect to CDN -->
  <link rel="preconnect" href="https://cdn.example.com">
  <link rel="dns-prefetch" href="https://cdn.example.com">

  <!-- Preload critical font -->
  <link rel="preload" href="/fonts/main.woff2" as="font" type="font/woff2" crossorigin>

  <!-- Preload critical CSS -->
  <link rel="preload" href="/css/critical.css" as="style">
</head>

Configuration

rules: {
  'resource-hints': {
    severity: 'info',
  },
}

core-web-vitals

Validates Core Web Vitals metrics (requires Lighthouse).

Metrics

LCP (Largest Contentful Paint): <2.5s good, >4s poor
CLS (Cumulative Layout Shift): <0.1 good, >0.25 poor
FCP (First Contentful Paint): <1.8s good, >3s poor
TTFB (Time to First Byte): <0.8s good, >1.8s poor
TBT (Total Blocking Time): <200ms good, >600ms poor
Performance Score: <50 poor, <90 needs improvement

Enable

# Install Lighthouse
npm install -D lighthouse chrome-launcher

# Analyze with Lighthouse
capyseo analyze https://example.com --lighthouse

Examples

Warning:

LCP: 3.2s (should be <2.5s)
CLS: 0.18 (should be <0.1)
Performance Score: 62/100

Pass:

LCP: 1.8s ✓
CLS: 0.05 ✓
FCP: 1.2s ✓
Performance Score: 94/100 ✓

Configuration

rules: {
  'core-web-vitals': {
    severity: 'warning',
  },
}

Performance Checklist

CSS

Bundle stylesheets (ideally 1-2)
Critical CSS inline, rest deferred
Remove unused CSS
Use CSS classes, not inline styles

JavaScript

Bundle scripts
Use async/defer
Minimize third-party scripts
Load non-critical scripts late

Loading

Preconnect to third-party origins
Preload critical resources
Lazy load below-fold content

Core Web Vitals

LCP < 2.5s
CLS < 0.1
FID < 100ms

Example Optimized Head

<head>
  <!-- Critical preconnects -->
  <link rel="preconnect" href="https://fonts.googleapis.com">
  <link rel="preconnect" href="https://cdn.example.com">

  <!-- Preload critical resources -->
  <link rel="preload" href="/fonts/inter.woff2" as="font" type="font/woff2" crossorigin>
  <link rel="preload" href="/css/critical.css" as="style">

  <!-- Critical CSS inline -->
  <style>
    /* Only above-fold styles */
  </style>

  <!-- Non-critical CSS deferred -->
  <link rel="stylesheet" href="/css/main.css" media="print" onload="this.media='all'">

  <!-- Scripts with defer -->
  <script src="/js/app.js" defer></script>
  <script src="https://cdn.example.com/analytics.js" async></script>
</head>