client:only directive and layout shift prevention

Direct Answer

No, Astro does not provide a built-in server-rendered fallback for client:only components. The directive explicitly omits the component from the initial HTML payload. The recommended approach to prevent Cumulative Layout Shift (CLS) is to reserve space in the server-rendered output using CSS on a wrapper element.

Why No Built-in Fallback Exists

The client:only directive is designed for components that depend exclusively on browser APIs (window, localStorage, IntersectionObserver, etc.) and cannot execute during SSR. Because these components have no server representation, Astro cannot render a fallback without defeating the purpose of bypassing SSR entirely. Any fallback would need to be static markup you provide yourself.

Recommended Configuration to Minimize Layout Shifts

1. Wrap the component in a container with explicit dimensions. Use min-height, aspect-ratio, or fixed width/height on a wrapper <div> that exists in the server HTML.
2. Match the placeholder size to the expected rendered size. If the component's dimensions are predictable from props (e.g., a chart with known width/height), compute an inline style on the wrapper: <div style="min-height: 300px; aspect-ratio: 16/9;"><MyChart client:only="react" /></div>.
3. Optional: add a lightweight skeleton or placeholder image. A low-overhead SVG or CSS gradient inside the wrapper improves perceived performance without adding significant payload.
4. Use CSS Grid/Flex with gap and min-height for dynamic lists or grids that populate client-side, so the container doesn't collapse to zero height before hydration.

Verification Steps

• Inspect the built HTML (dist/ or devtools Network tab) to confirm the client:only component's markup is absent.
• Open Chrome DevTools → Performance, enable "Layout Shift" tracking, reload, and verify no shift occurs before the component mounts.
• Run a Lighthouse audit; target CLS ≤ 0.1.

One Diagnostic Detail Needed

Does the final rendered size of your client:only component depend on runtime measurements (e.g., text measuring, user-generated content, or responsive breakpoints that can't be predicted from props)? If yes, static CSS placeholders may be insufficient and you'll need a client-side measurement + resize strategy after mount.