Client Directives Still Include JS in Critical Rendering Path

[VashJuan]

Astro Info

Astro                    v6.0.0-beta.14
Node                     v25.6.1
System                   Windows (x64)
Package Manager          pnpm
Output                   static
Adapter                  none
Integrations             @astrojs/svelte
                         @astrojs/mdx
                         @vite-pwa/astro-integration
                         @astrojs/sitemap

If this issue only occurs in one browser, which browser is a problem?

No response

Describe the Bug

Astro Bug Report: Client Directives Still Include JS in Critical Rendering Path

Description

All Astro client directives (client:load, client:idle, client:only) bundle JavaScript in the initial page load, causing non-critical components to block LCP (Largest Contentful Paint) measurement. There appears to be no way to truly defer a component's JavaScript until after the window load event completes.

Issue

We have a decorative FloatingImages Svelte component that should load after LCP to avoid impacting performance metrics. Despite trying all available client directives, the component's JavaScript always appears in the critical rendering path and delays LCP measurement.

Steps to Reproduce

1. Create a Svelte component wrapped in an Astro component
2. Use any client directive: client:load, client:idle, client:only="svelte", or client:media
3. Build the site and deploy
4. Run Lighthouse performance test
5. Observe Network Dependency Tree in Lighthouse report

Expected Behavior

With client:load, the component's JavaScript should:

• Not be included in the initial HTML response
• Start downloading after the window load event fires
• Not appear in Lighthouse's critical rendering path
• Not impact LCP measurement

With client:only, the component should:

• Skip server-side rendering (this works)
• Have its JavaScript completely deferred from initial bundle
• Load asynchronously after page is interactive

Actual Behavior

All client directives include the component's JavaScript in the initial page bundle:

Network Dependency Tree (from Lighthouse):

Initial Navigation
https://vashonmesh.org - 76 ms, 28.31 KiB
├── /_astro/FloatingImages.DIgMZlMV.js - 247 ms, 2.57 KiB
├── /_astro/client.svelte.CX8gQjlJ.js - 247 ms, 0.67 KiB
├── /_astro/template.Cwu_fZMk.js - 504 ms, 8.62 KiB
├── /_astro/render.BvwD2nt8.js - 503 ms, 2.96 KiB
└── /_astro/lifecycle.DoIy0IOf.js - 503 ms, 2.22 KiB

Result:

• LCP increased from 1.2s → 8.3s
• Component JavaScript in critical path despite client:only="svelte"
• No apparent way to defer loading until after LCP measurement

Tested Workarounds

Attempt 1: client:idle

<FloatingImagesClient client:idle />

• Result: Scripts load before window load event
• LCP Impact: 8.9s

Attempt 2: client:load

<FloatingImagesClient client:load />

• Result: Scripts still bundled in initial HTML, just delayed execution
• LCP Impact: 3.0s

Attempt 3: client:only="svelte"

<FloatingImagesClient client:only="svelte" />

• Result: Skips SSR but JavaScript still in critical path
• LCP Impact: 8.3s

Attempt 4: Manual Chunk Splitting

// astro.config.mjs
build: {
  rollupOptions: {
    output: {
      manualChunks: (id) => {
        if (id.includes("FloatingImages")) return "floating-images";
      };
    }
  }
}

• Result: Build errors (missing Zod dependencies from Astro internals)

Attempt 5: requestIdleCallback in Svelte

onMount(() => {
  if ('requestIdleCallback' in window) {
    requestIdleCallback(startAnimation, { timeout: 2000 });
  }
});

• Result: Only delays animation start, not JavaScript loading
• LCP Impact: Still 8.3s (scripts loaded early)

Code Example

FloatingImages.astro:

---
import FloatingImagesClient from "./FloatingImages.svelte";
const { imageCount = 12 } = Astro.props;
// ... image optimization code ...
---

<FloatingImagesClient
  client:only="svelte"
  floatingImageItems={floatingImageItems}
  keyframesCss={keyframesCss}
/>

Layout.astro:

{floatingImages && <FloatingImages imageCount={imageCount} />}

Environment

• Astro: 6.0.0-beta.14
• Svelte Integration: @astrojs/svelte
• Build Tool: Vite
• Node: 22.12.0
• Package Manager: pnpm

Desired Solution

One of:

1. New directive: client:defer that:

   • Completely excludes component from initial bundle
   • Loads JavaScript only after window load event + requestIdleCallback
   • Does not appear in Lighthouse critical rendering path

2. Enhanced client:load:

   • Should truly defer loading until after window load
   • Should not bundle scripts in initial HTML response
   • Should use dynamic import at runtime

3. Configuration option:

   <Component client:load={{ defer: true, priority: "low" }} />

4. Documentation: If this is by design, document how to achieve true deferred loading for non-critical components

Impact

This limitation makes it impossible to have decorative/non-essential components that don't impact Core Web Vitals (LCP, TBT). For sites focused on performance scores (Google PageSpeed, Lighthouse), this forces removal of visual enhancements.

Temporary Solution

Currently, we've completely disabled the component:

<!-- FloatingImages temporarily disabled to fix LCP --><!-- TODO: Need Astro support for truly deferred component loading -->

This is not ideal as the feature adds visual interest to the site.

References

• Astro Islands Documentation
• Client Directives Reference
• Web.dev: Optimize LCP
• Chrome Lighthouse Network Dependency Analysis

Additional Context

Our memory notes from multiple debugging sessions:

- ANY hydration directive except `client:only` adds JS to initial bundle (proven false - client:only also bundles)
- `client:idle` fires too early, before window load
- `client:load` waits for window load BUT still bundles scripts in initial HTML
- Manual chunk splitting causes build errors (missing Zod dependencies)
- Dynamic imports of Astro components not supported at runtime

We've spent considerable time trying every available approach and conclude this is a framework limitation rather than implementation error.

What's the expected result?

See above

Link to Minimal Reproducible Example

See main bug report

Participation

• I am willing to submit a pull request for this issue.

[VashJuan]

Feel free to reference github.com/VashonMesh.github.io if necessary

[astrobot-houston]

I was unable to reproduce this issue. The component JavaScript is not included in the critical rendering path in the traditional sense — there are no <link rel="modulepreload"> tags, no synchronous <script src=""> tags, and no HTTP preload headers in the generated HTML. All component JS is loaded exclusively via dynamic import() triggered by the <astro-island> custom element. For client:load and client:only, the import is triggered immediately when the element connects to the DOM during HTML parsing, which is why Lighthouse's network dependency analysis shows these as part of the initial load chain — this is the intended behavior of these directives. For client:idle, loading is deferred to requestIdleCallback, which should not directly block LCP.

Fix: I was unable to find a fix for this issue. This is expected behavior rather than a bug — each client directive works as documented. The dramatic LCP regression (1.2s → 8.3s) is likely caused by total JS payload size, network conditions, or bandwidth competition on slower connections rather than the loading mechanism itself. As workarounds: (1) use client:visible to defer loading until the component scrolls into view, (2) use a vanilla JS approach with window.addEventListener('load', () => { ... }) to dynamically create the component after load, or (3) consider whether a pure CSS animation could replace the decorative component entirely without requiring JS. The core request — a directive that completely excludes component JS until after the window load event — would be a new feature (e.g., client:defer) rather than a fix to existing behavior.

Priority: [P2: nice to have]. This is a feature request for a new loading strategy rather than a bug in existing functionality. All current client directives are working as designed and documented. Users who need truly deferred loading for non-critical decorative components have viable workarounds (client:visible, manual dynamic imports), though a built-in client:defer directive would improve the developer experience for performance-sensitive sites.

Full Triage Report

Triage Report: Issue #15606 — Client Directives Still Include JS in Critical Rendering Path

Issue Summary

Title: Client Directives Still Include JS in Critical Rendering Path
Author: VashJuan
URL: #15606
State: OPEN
Labels: needs triage

Description

The reporter claims that all Astro client directives (client:load, client:idle, client:only) bundle JavaScript in the initial page load, causing non-critical components to block LCP (Largest Contentful Paint). They have a decorative FloatingImages Svelte component and report LCP increased from 1.2s to 8.3s when using client directives. They want a way to completely exclude a component's JavaScript from the initial page bundle.

Reporter's Environment

• Astro v6.0.0-beta.14
• Node v25.6.1 (unusual — likely a typo, likely meant v22)
• Windows (x64)
• @astrojs/svelte integration
• Static output mode

Reproduction Details

Setup

• Created a reproduction project using the framework-svelte example template
• Created a FloatingImages Svelte component (simple decorative component with animations)
• Created three pages testing client:load, client:idle, and client:only="svelte" directives
• Created a baseline page with no client-side components
• Built using astro build (static mode)
• Astro v6.0.0-beta.14 (monorepo head)

Build Output Analysis

Generated JS files:

• FloatingImages.DujQOPe_.js — 6.23 KiB
• client.svelte.qtSEOrsf.js — 6.34 KiB
• template.Ch9cKu-H.js — 18.76 KiB

Key findings from HTML output analysis:

1. No <link rel="modulepreload"> tags — Component JS files are NOT preloaded in the HTML
2. No <script src="/_astro/..."> tags — Component JS files are NOT loaded via traditional script tags
3. No Link: <...>; rel=modulepreload HTTP headers — No server-side preload hints
4. Two small inline <script> tags per page:
   • Directive handler script (e.g., the client:load handler, ~130 bytes)
   • astro-island custom element definition (~2KB minified)
5. Component URLs stored as HTML attributes — component-url and renderer-url on <astro-island> element
6. Baseline page (no components) has zero JavaScript

How the Loading Actually Works

The <astro-island> custom element uses this flow:

1. connectedCallback() → childrenConnectedCallback() → start()
2. start() calls Astro[directive](callback, opts, this)
3. The callback does import(componentUrl) and import(rendererUrl) — dynamic imports

Per directive:

• client:load: Immediately invokes the callback → triggers import() as soon as the custom element connects to DOM
• client:only: Same as client:load but without SSR (no server-rendered HTML)
• client:idle: Defers to requestIdleCallback (or setTimeout(cb, 200) as fallback) before triggering import()
• client:visible: Uses IntersectionObserver before triggering import()
• client:media: Uses matchMedia before triggering import()

Reproduction Result: NOT REPRODUCED as a bug

The behavior the reporter describes — component JS appearing in Lighthouse's "Network Dependency Tree" — is expected behavior, not a bug:

1. The JS is NOT in the critical rendering path in the traditional sense. There are no preload tags or synchronous script tags.
2. For client:load and client:only, the dynamic import() is triggered immediately during HTML parsing — this is by design.
3. For client:idle, the import() is deferred to requestIdleCallback, which should not impact LCP.
4. The reporter's dramatic LCP regression is likely caused by total JS payload size, network conditions, or bandwidth competition rather than the loading mechanism.
5. The user is essentially requesting a new feature — a client:defer directive.

Suggested Workarounds

1. Use client:visible — defers loading until the component is in the viewport
2. Use vanilla JS with window.addEventListener('load', ...) to dynamically create the component
3. Consider pure CSS animations for decorative effects without JS

Verdict

Not Reproduced — The described behavior is expected/by-design for client directives. This is a feature request, not a bug.

This report was made by an LLM. Mistakes happen, check important info.

[VashJuan]

The Problem

Decorative components (like animated FloatingImages) bundled with any Astro client directive (client:load, client:only, client:visible) appear in the critical rendering path, blocking LCP until the component hydrates. Even with requestIdleCallback(2s timeout) in the Svelte component to defer animations, the JavaScript bundle still delays the LCP element (in our case, the hero logo).

Test Results (Live Netlify Deployment)

client:only="svelte": LCP 8.4s (worst - bundles in initial HTML)
client:load: LCP 3.0s (still delays LCP)
client:visible: LCP 3.0s (position:fixed makes immediately visible)
Disabled completely: LCP 1.2s ✅ (best)

Key Insights

All client directives load JS in the initial bundle - This is the root cause. The element triggers dynamic imports during HTML parsing, not after page load.
requestIdleCallback only defers animation start, not component hydration/JS loading

Astro's islands architecture has fundamental limits for deferring non-critical decorative components until after LCP

Guidance for Others

If your decorative component is less important than LCP performance:

Disable it completely
Accept that you can't have both animations AND fast LCP with Astro's current islands model

If animations are critical:
Consider pure vanilla JS outside the Astro component system with window.addEventListener('load')
Or accept the LCP penalty (~3-8s depending on directive)

A feature request that could help: A client:afterLoad or client:afterLCP directive that truly defers hydration until after the window load event completes.

Final Configuration (For Reference)
Performance: LCP 1.2s, FCP 0.9s, CLS 0.002

[VashJuan]

With more testing, we may have found a solution:
switching from client:visible (3.0s) to client:load (1.2s), defers hydration until the window's full load event completes. LCP went down once to 0.9-1.2 seconds. I'm hopeful this resolves our issue for now. Still adding the new directive might help others in a similar place?

[matthewp]

Are you saying that client:load does defer loading? Your original bug report was wrong?

[VashJuan]

The bug report was partially wrong in its conclusions, but the observations were accurate. Here's what we learned:

What the report got right:

FloatingImages JS is in the initial page bundle regardless of directive — the Lighthouse network dependency tree shows scripts downloading immediately. That's factually accurate and still true.

The scripts download early (they're in the bundle), but client:load correctly defers their execution until after the load event, which is after LCP.

client:idle fires before window.load in many conditions — that was the real regression culprit (8.9s LCP), not client:load.

Short answer: Yes, client:load does defer execution appropriately. The original bug report's client:load measurement was wrong due to a separate confounding issue, and the desired behavior (client:defer / post-LCP loading) is effectively achievable with client:load as-is.

Sorry, but we (AI & I) did waste a quite few days gyrating through this.