Dynamic Import Client Only Support

[BurkeDesigns]

Body

Summary

Allow Astro to hydrate dynamically imported framework components (e.g., React .tsx) when used with client:* directives—so await import() + client:only (or other client directives) works reliably without runtime errors. ([GitHub]1)

Background & Motivation

Today, if you dynamically import a component and add client:only, Astro fails to render it on the client; removing client:only makes it render but non-interactive, defeating the purpose of client hydration. This gap blocks legitimate code-splitting/lazy-loading patterns common in larger apps and forces awkward workarounds or fully static rendering where interactivity is needed. ([GitHub]1)

User problem: “When you dynamically import any react tsx component and then use the client:only directive, Astro cannot render it on the client and throws an error… without client:only, it renders but is not interactive.” ([GitHub]1)

Why now: Projects increasingly rely on lazy loading to control bundle size and TTI. Astro v5’s ecosystem encourages islands + partial hydration; dynamic imports should be a first-class companion to those patterns.

Goals

• Hydrate dynamically imported components that are passed through client:* directives (client:only, client:load, client:visible, etc.) without runtime errors.
• Preserve code-splitting benefits: ensure chunks produced by import() are properly discovered, bundled, and loaded before hydration.
• Keep authoring ergonomics: allow existing client:* syntax to work with dynamic imports with no special wrappers or proprietary helpers.
• Framework-agnostic behavior: the fix should work for React/Vue/Svelte/Solid integrations consistently.
• Predictable errors & DX: if a dynamic import cannot be hydrated (e.g., wrong default export), surface a clear, actionable error.

Example

---
// ✅ Desired: lazy-load a React component and hydrate it on the client
const Chart = (await import('../components/Chart.tsx')).default;
---
<Chart client:only="react" />

Or even better (ideal senerio):

---
// ✅ Desired: lazy-load a React component and hydrate it on the client
const Chart = await import('../components/Chart.tsx');
---
<Chart client:only="react" />

Or, with conditional/lazy evaluation:

---
let Widget;
if (Astro.props.enableWidget) {
  Widget = (await import('../components/Widget.tsx')).default;
}
---
{Widget && <Widget client:visible="react" />}

Both examples should (a) split the component into a separate chunk, (b) load that chunk on the client when required by the directive, and (c) hydrate it without errors—addressing the current failure described in the issue. ([GitHub]1)