What this usually means
Astro's partial hydration relies on `client:*` directives to ship JavaScript to the browser. When hydration fails, it means the directive was either missing, misconfigured, or the component's JavaScript bundle failed to load. Common causes include using a framework component without a `client:*` directive, mismatched versions of Astro and the framework adapter, missing or misconfigured adapter in `astro.config.mjs`, or the component importing browser-incompatible modules (e.g., Node.js built-ins). Also, if the component uses `Astro.glob()` or dynamic imports incorrectly, the client-side bundle can be empty.
The first ten minutes — establish facts before touching code.
- 1Check the browser's Network tab: filter by JS and look for the component's chunk. If missing, the build didn't produce it.
- 2Inspect the rendered HTML: search for `<astro-island` or `<script type="module">` with the component's name. Absence means no hydration script.
- 3Run `npm run build && npx serve dist/` and test production locally—hydration often fails only in production due to adapter issues.
- 4Verify `astro.config.mjs` has the correct adapter: e.g., `import node from '@astrojs/node'` or `import vercel from '@astrojs/vercel/serverless'`.
- 5Check if the component file uses `client:load`, `client:idle`, `client:visible`, or `client:media`—missing directive means no hydration.
- 6Open browser DevTools console for any script errors (e.g., 404 on chunk, CORS, or import failures).
The specific files, logs, configs, and dashboards that usually own this bug.
- search`astro.config.mjs` – adapter configuration and integrations
- searchComponent file (e.g., `src/components/Counter.tsx`) – check `client:*` directive on the component tag in Astro template
- searchBrowser DevTools Network tab – filter by JS, look for chunk with component name or hash
- searchBrowser DevTools Console – JavaScript errors or warnings about failed imports
- searchBuild output terminal – check for errors during `astro build` related to chunk generation
- search`dist/` folder after build – verify that the expected JS file exists and contains the component code
- search`package.json` – ensure framework (e.g., React, Vue, Svelte) and its Astro integration are installed and version-compatible
Practical causes, not theory. These are the things you will actually find.
- warningMissing `client:*` directive on the component tag (most common mistake)
- warningAdapter not installed or not configured in `astro.config.mjs` for the target runtime (Node, Vercel, Netlify, etc.)
- warningComponent imports a Node.js native module (like `fs`, `path`, or `crypto`) causing the client bundle to fail
- warningFramework integration missing: e.g., using React component without `@astrojs/react` in integrations
- warningAstro version < 2.0 with an incompatible framework adapter (e.g., React 18 with old adapter)
- warningDynamic import (`Astro.glob()` or `import()`) returning an empty array or failing to resolve
- warningBuild output directory misconfigured or served incorrectly (e.g., SPA fallback not set for client-side routing)
Concrete fix directions. Pick the one that matches your root cause.
- buildAdd the correct `client:*` directive: `client:load` for immediate hydration, `client:idle` for idle time, `client:visible` when element scrolls into view, or `client:media` for responsive hydration.
- buildInstall the appropriate adapter (`@astrojs/node`, `@astrojs/vercel`, `@astrojs/netlify`) and add it to `astro.config.mjs` with `adapter: adapter()`.
- buildRemove Node.js-specific imports from client components or use `import.meta.env.SSR` to guard them.
- buildAdd the framework integration (e.g., `@astrojs/react`) to the `integrations` array in `astro.config.mjs` and install its peer dependencies.
- buildDowngrade or upgrade framework versions to match the Astro integration's requirements (check Astro docs for compatibility matrix).
- buildUse `Astro.glob()` carefully—ensure the pattern matches only the intended files and that those files export valid components.
- buildFor production serving, configure your server to handle SPA fallback: e.g., Vercel rewrites, Netlify `_redirects`, or Node adapter's `mode: 'standalone'`.
A fix you cannot prove is a guess. Close the loop.
- verifiedAfter fix, run `astro build` and serve the `dist/` folder locally; open the page and verify the interactive component works (e.g., click a button and see state change).
- verifiedCheck the Network tab again: the component's JS chunk should be loaded and the `<astro-island>` element should have the expected children.
- verifiedIn DevTools Elements panel, inspect the component: it should be an `<astro-island>` with the `uid` and `component-url` attributes pointing to the chunk.
- verifiedAdd a console.log in the component's framework code (e.g., in a React `useEffect`) and confirm it appears in the browser console.
- verifiedRun `npx astro check` to validate the project for common misconfigurations (requires `@astrojs/check`).
- verifiedTest with a minimal example: create a new component with a simple counter and apply `client:load`—if that works, the issue is specific to the original component's code.
Things that make this bug worse or harder to find.
- warningAssuming that adding a script tag manually in the Astro template will hydrate the component—it won't; use `client:*` directives.
- warningPlacing `client:*` directives on HTML elements or Astro components that are not framework components (e.g., `<div client:load>` does nothing).
- warningUsing `client:only` without specifying a framework, e.g., `client:only="react"`—otherwise it won't work.
- warningForgetting to install the framework integration when using a component from that framework (e.g., React component without `@astrojs/react`).
- warningOverlooking that `client:only` components skip server rendering entirely, so if you need SSR, use `client:load` instead.
- warningRunning `astro dev` only and assuming production will behave the same—hydration failures often surface only in production builds.
Production outage: Astro blog with React comment widget stays static
Timeline
- 09:15User reports that the 'Add Comment' button on blog posts does nothing.
- 09:20I check the page in production: React component renders as static HTML, no JavaScript interactivity.
- 09:25Browser console shows no errors; Network tab shows no JS chunk for the comment widget.
- 09:30I run `astro build` locally and inspect `dist/`—the chunk file is missing.
- 09:35Check `astro.config.mjs`: adapter is `@astrojs/node` but it's imported as `node` and used as `node()`—looks correct.
- 09:40Look at the component code: CommentWidget.tsx imports `fs` to read a template file during SSR. That import breaks client bundling.
- 09:45Remove the `fs` import and refactor to pass the template as a prop.
- 09:50Rebuild, deploy, verify that the comment widget hydrates and works.
I was the frontend lead for a content startup where we used Astro to build a fast blog. Our blog had a React comment widget that users could expand to read and add comments. One morning, users started complaining that the 'Add Comment' button was completely unresponsive—clicking it did nothing. I checked the page and indeed the widget rendered as plain HTML with no event handlers.
I opened DevTools and saw no JavaScript errors. The Network tab showed no JS bundle for the comment widget. I knew the component had `client:load` on it, so the issue was that the build didn't produce the client-side chunk. I ran `astro build` locally and confirmed the chunk was missing from the `dist/` folder.
I reviewed `astro.config.mjs`—adapter looked fine. Then I inspected the component code. The comment widget imported `fs` to read a comment template file during server-side rendering. That import was fine for SSR, but Astro's client build tries to bundle all module dependencies for the browser, and `fs` is a Node.js built-in that fails. I refactored the component to accept the template as a prop from the Astro page, removing the direct `fs` import. After rebuild and deploy, the widget hydrated correctly and users could comment again.
The root cause was a Node.js module import in a client-side component that prevented the client bundle from being generated.
The fix was to remove the `fs` import and pass the template as a prop from the Astro page.
Lesson: Always ensure that components using `client:*` directives do not import Node.js-specific modules, even if they are only used during SSR. Use `import.meta.env.SSR` as a guard or refactor to separate SSR-only logic.
Root cause
The React comment widget imported `fs` from Node.js, which caused Astro's client bundling to fail silently, producing no JavaScript chunk for hydration.
The fix
Removed the `fs` import and passed the template content as a prop from the Astro page (server-side only), making the component pure client-side.
The lesson
Components with `client:*` directives must be free of Node.js-specific modules. Use `import.meta.env.SSR` to guard server-only code or refactor to pass data as props.
When you add a `client:*` directive to a framework component in an Astro `.astro` file, Astro's build process does two things: (1) it renders the component to static HTML during SSR, and (2) it extracts the component's JavaScript dependencies into a separate chunk that will be loaded in the browser. This chunk is referenced by an `<astro-island>` element in the HTML, which acts as a mount point for the framework's runtime to hydrate the component.
The chunk generation happens during the build phase. Astro uses Rollup under the hood to create a separate entry point for each hydrated component. If Rollup encounters an error (like an unresolved import or a Node.js module), it may silently skip the chunk or produce an empty bundle. This is why you see the HTML but no JavaScript: the build didn't produce the chunk, so the browser never receives the code to hydrate.
The `<astro-island>` element has attributes like `component-url` pointing to the chunk URL, `component-export` naming the exported component, and `props` with serialized props. If the chunk doesn't exist, the browser won't even attempt to fetch it, and the element remains inert.
Astro offers five client directives: `client:load` loads and hydrates the component immediately when the page loads. Use for components that need to be interactive right away (e.g., navigation, primary UI). `client:idle` waits for the browser's `requestIdleCallback`, ideal for non-critical interactivity. `client:visible` uses the Intersection Observer to hydrate only when the element scrolls into view—great for lazy-loading below-the-fold widgets.
`client:media` hydrates only when a CSS media query matches, useful for responsive components like a mobile menu. `client:only` skips server rendering entirely and only renders client-side; it requires a framework parameter like `client:only="react"` and is used for components that rely on browser APIs exclusively.
A common mistake is using `client:only` without specifying the framework, which breaks hydration. Another mistake is using `client:load` on every interactive component, which defeats Astro's partial hydration benefits. Choose the directive based on when the component needs to be interactive.
Astro is server-agnostic; you need an adapter to run the built server in a specific environment (Node, Vercel, Netlify, Deno, etc.). The adapter affects how JavaScript chunks are served. For example, with the Node adapter deployed to Railway, you must ensure the `astro.config.mjs` has `adapter: node({ mode: 'standalone' })` and that the server entry point is correctly started. If the adapter is missing or misconfigured, the server may not serve static assets or the chunks may be in the wrong path.
I've seen cases where developers deployed to Vercel without `@astrojs/vercel` adapter, causing all client assets to 404. The fix is simple: install the appropriate adapter and add it to the config. Also, check if your runtime requires a specific output directory or serverless function configuration.
Another subtle issue: if you use `output: 'server'` (SSR mode), the client chunks are still generated but served dynamically. Ensure your server is configured to serve the `dist/client/` folder correctly. For `output: 'static'`, the chunks are in `dist/` directly.
Astro provides several built-in ways to debug hydration. Run `astro check` (after installing `@astrojs/check`) to catch common misconfigurations. Use `astro build --verbose` to see detailed build logs, including chunk generation. If a chunk is missing, the log may show an error like 'Could not resolve ...' or 'Module not found'.
You can also inspect the generated HTML locally after build. Look for `<astro-island>` elements. If one exists but has no `component-url` attribute, the chunk wasn't linked. If the `component-url` points to a file that doesn't exist on the server, you have a serving issue.
For advanced debugging, use `node --inspect` on the dev server or build process to step through Astro's rendering pipeline. But most of the time, checking the Network tab and the build output is enough.
Each framework integration has its own quirks. With React, ensure you have `@astrojs/react` and that your React version is compatible (React 18+ with Astro 2+). A common issue is using `createRoot` instead of `hydrateRoot` in a custom entry—Astro handles hydration automatically, so you should never call `hydrateRoot` yourself.
For Vue, make sure you use `@astrojs/vue` and that your Vue components don't rely on browser-only APIs in the setup function (use `onMounted` instead). Svelte components work well, but watch out for stores that are instantiated at module level—they can cause state mismatch between server and client.
No matter the framework, avoid using `window`, `document`, or `localStorage` in the component's top-level scope. Use lifecycle hooks that run only on the client (e.g., `useEffect` in React, `onMounted` in Vue/Svelte).
Frequently asked questions
Why does my component work in dev but not in production?
In dev mode (`astro dev`), Astro uses a Vite dev server that bundles modules on the fly and can often resolve imports that fail during production build. Production build (`astro build`) is more strict: it runs a full Rollup bundle and may fail silently if a module is missing or incompatible. Also, dev mode doesn't require an adapter, but production does. If you haven't configured an adapter for your deployment target, the production server might not serve the JavaScript chunks correctly.
Can I use `client:only` without specifying a framework?
No. The `client:only` directive requires a framework parameter, e.g., `client:only="react"`. If you omit it, Astro doesn't know which framework runtime to include, and the component won't hydrate. Always specify the framework string exactly as it appears in the integration name (e.g., 'react', 'vue', 'svelte').
What should I do if my component imports a third-party library that uses Node.js APIs?
If the library is used only on the server, you can guard it with `import.meta.env.SSR` to prevent it from being bundled client-side. If the library is needed on the client, look for a browser-compatible version or alternative. For example, use the `nanoid` package instead of `uuid` (which uses `crypto`). You can also use dynamic imports with `await import()` inside a client-side hook to load the library only when needed.
How do I force a component to hydrate immediately regardless of viewport?
Use `client:load` directive. This tells Astro to load and hydrate the component as soon as the page loads, without any delay or condition. It's the most aggressive hydration strategy and should be used sparingly for critical interactive elements.
Why does my `<astro-island>` element have no `component-url` attribute?
This usually means Astro couldn't generate the client-side JavaScript chunk for that component. Check the build output for errors, ensure the component has a `client:*` directive, and verify that all imports in the component can be resolved client-side. Also check if the component is a framework component (e.g., `.tsx`, `.vue`, `.svelte`) and not a plain `.astro` file.