Performance Optimization

Pagesmith provides static generation, image processing, font hosting, and caching controls. The finished site’s performance still depends on its content, layout, scripts, integrations, and visitor conditions. Measure the published page before deciding what to change.

Why Performance Matters

• User experience: Visitors can read and interact with the page sooner
• Search: Core Web Vitals are one part of Google’s page experience systems
• Access: Smaller pages work better on slow connections and modest devices
• Transfer: Smaller assets use less bandwidth

Measuring Performance

Lighthouse

Chrome DevTools includes Lighthouse:

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

Lighthouse scores are lab measurements, not guarantees about every visitor. Test the same page more than once and investigate the individual findings. Use field data when enough real-user data is available.

Core Web Vitals

Google’s key metrics:

Image Optimization

Images are often among the largest page assets. Pagesmith processes supported uploads, but you still choose the source, dimensions, placement, alt text, and loading behavior.

What Pagesmith does for you

When you upload an image (or the AI fetches one for you), the image fetcher service:

• Converts supported images to WebP using the configured quality setting
• Generates responsive variants at widths up to 1536, 1024, 768, 640, and 320 pixels while preserving the aspect ratio
• Skips upscaling when the source is narrower than a configured variant
• Serves generated variants from the Pagesmith CDN when the project uses the managed image workflow
• Uses high-quality resampling (Lanczos) for the downscaled versions

Check the generated markup and published response when image behavior is important. Images added directly to code or loaded from third parties may not use the managed image workflow.

What you still control

• Source resolution: Upload an original large enough for its displayed size. The managed workflow does not upscale it.
• Alt text: Describe informative images for people who cannot see them. Use an empty alt value for decorative images.
• Lazy loading: Keep the likely LCP image eager. Use loading="lazy" for suitable below-the-fold images:

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

• Do not load unused images: If a section is conditional, avoid rendering its image when the section is absent.

Minimizing JavaScript

Astro can limit browser JavaScript to interactive components. A project can still become JavaScript-heavy if it hydrates many components or adds large third-party scripts.

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

Pagesmith uses Tailwind. Only classes you actually use end up in the CSS shipped to the browser, so adding utility classes liberally won’t bloat the bundle.

Critical CSS

For above-fold content, inline critical CSS:

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

Font Optimization

Fonts selected through the Pagesmith font registry are served with the project rather than fetched from Google Fonts at runtime. Check the published network requests if fonts were added directly in project code. See Typography for the font workflow.

What you still control:

Limit font files

Each font file is a request. Keep it minimal:

• 1–2 font families max
• 2–3 weights per family
• Prefer variable fonts where the design allows

Subset when you can

If your site only ever uses Latin characters, ask the AI to use a Latin-only subset of your chosen font.

Third-Party Scripts

Analytics, chat widgets, embeds, and other external scripts can add network and main-thread work. Measure their effect on the published page.

Use built-in integrations where possible

Use the supported analytics integrations when they meet your needs. Confirm their consent behavior and loading strategy in the generated project.

Async / defer

If you do hand-add a third-party script, use async or defer so it doesn’t block rendering:

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

Load chat widgets on interaction

Consider loading a chat widget after the visitor asks to use it. Test whether delayed loading affects the support experience or vendor setup.

Caching

Pagesmith hosting sets caching behavior for deployed assets. Inspect response headers when you need to confirm a specific route.

Static assets

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

HTML

HTML generally uses a shorter cache policy than hashed assets. Wait for publishing to finish, then check the live URL and response headers.

Performance Checklist

Images (most is automatic):

• Upload high-resolution source images
• Set alt text on every image
• Lazy load below-the-fold images
• Don’t ship hidden/unused images

JavaScript:

• Islands only where needed
• Proper client: directives (visible, idle, load)
• No unused dependencies

Fonts:

• Limited font files (1–2 families, 2–3 weights)
• Use variable fonts where possible

Third-party:

• Use built-in integrations rather than hand-added scripts where possible
• async or defer on any manual <script> tags
• Load chat widgets on interaction, not on page load

Related Docs

• Key Concepts: Static generation and islands
• Typography: Font registry and self-hosting
• SEO Guidance: Technical search foundations
• Publishing: Pagesmith hosting workflow