Performance Optimization

Pagesmith sites are fast by default (SSG). Here's how to optimize further.

Why Performance Matters

• User experience — Fast sites convert better
• SEO — Page speed is a ranking factor
• Accessibility — Works on slow connections
• Costs — Less bandwidth, cheaper hosting

Measuring Performance

Lighthouse

Chrome DevTools includes Lighthouse:

1. Open DevTools (F12)
2. Go to Lighthouse tab
3. Click "Analyze page load"
4. Review scores

Target scores:

• Performance: 90+
• Accessibility: 90+
• Best Practices: 90+
• SEO: 90+

Core Web Vitals

Google's key metrics:

Image Optimization

Images are usually the biggest performance impact.

Format

Use WebP instead of PNG/JPG:

• 25-35% smaller file sizes
• Same visual quality
• Wide browser support

Sizing

Serve appropriately sized images:

<!-- Don't serve 4000px image for 400px container -->
<img src="hero.webp" width="800" height="600">

Lazy Loading

Load images only when needed:

<img src="image.webp" loading="lazy">

Apply to below-fold images. Keep above-fold images eager.

Compression

Before uploading:

• Use Squoosh or similar
• Target 80-85% quality
• Check visual quality after compression

Minimizing JavaScript

Pagesmith uses Astro's islands architecture — JavaScript only where needed.

Client Directives

<!-- Only loads JS when visible -->
<Counter client:visible />

<!-- Only loads JS when idle -->
<Analytics client:idle />

<!-- Loads JS immediately (use sparingly) -->
<Form client:load />

Reduce Dependencies

Ask: Does this component need JavaScript?

• Static content → No JS needed
• Forms → Minimal JS
• Complex interactivity → JS island

CSS Optimization

Tailwind Purging

Pagesmith uses Tailwind with automatic CSS purging. Only used classes ship.

Critical CSS

For above-fold content, inline critical CSS:

<style is:inline>
  /* Critical styles for first paint */
</style>

Font Optimization

Font Display

Use font-display: swap to prevent layout shift:

@font-face {
  font-family: 'Custom';
  font-display: swap;
  src: url('/fonts/custom.woff2');
}

Subset Fonts

Only include characters you use. Latin subset is usually enough.

Limit Font Files

Each font file is a request:

• 1-2 font families max
• 2-3 weights per family
• Prefer variable fonts

Third-Party Scripts

External scripts (analytics, chat, etc.) can hurt performance.

Load Asynchronously

<script async src="https://analytics.example.com/script.js"></script>

Defer When Possible

<script defer src="..."></script>

Consider Alternatives

• Analytics: Plausible/Fathom (lighter than GA)
• Fonts: Self-host instead of Google Fonts
• Chat: Load on interaction, not page load

Caching

Pagesmith's edge deployment handles caching automatically.

Static Assets

Images, CSS, JS get long cache times. Content is hashed for cache busting.

HTML

HTML has shorter cache for freshness. Deploys update instantly.

Performance Checklist

Images:

• [ ] WebP format
• [ ] Appropriate dimensions
• [ ] Lazy loading on below-fold
• [ ] Compressed

JavaScript:

• [ ] Islands only where needed
• [ ] Proper client directives
• [ ] No unused dependencies

Fonts:

• [ ] Limited font files
• [ ] font-display: swap
• [ ] Subsetted or self-hosted

Third-party:

• [ ] Async/defer scripts
• [ ] Minimal trackers
• [ ] Light alternatives

Related Docs

• Key Concepts — SSG and islands
• SEO Best Practices — Speed affects ranking
• Publishing — Edge deployment