Bug tracking for Astro — session replay, console + HAR (2026)
3 min read · JavaScript
What Astro teams ship with BugMojo
Astro's pitch is "ship zero JavaScript by default" — but the bugs your team will hit are not in the static HTML, they're at the **island boundaries**. A `<MyButton client:visible />` hydrates only when scrolled into view; a `<MyForm client:load />` hydrates on every page. Picking the wrong directive turns a 0-KB page into a 200-KB page, or a fast page into a janky one.
A useful Astro bug report needs the page route (static, server, hybrid?), the island component name + client directive, and what the user saw before AND after hydration. BugMojo captures both halves — the server-rendered HTML and the client takeover — in the same replay.
This guide covers Astro island hydration gotchas, view transitions bugs (Astro's native router), and the recommended BugMojo capture workflow for Astro teams in 2026.
Astro gotchas
Framework-specific failure modes our team has shipped through. Each one is hard to spot in a screenshot — easy to spot in a session replay.
Client directives pick up the wrong framework
Medium impactIf your project has both `@astrojs/react` and `@astrojs/preact` integrated, mixing them in islands causes silent bundle bloat. Each framework ships its own runtime.
client:visible doesn't fire above the fold
Medium impactA `client:visible` island that is already in the viewport on page load still uses IntersectionObserver, which fires after first paint. The result: a brief moment where the island appears static. Use `client:load` for above-the-fold interactive content.
View transitions break form re-renders
Medium impactAstro's view transitions persist DOM across navigations. A `<form>` element that survives the transition retains its previous values — surprising users and breaking single-page-app expectations.
SSR mode requires choosing an adapter — without one, server endpoints 404
High impactAstro's static mode (the default) ignores server endpoints. Add `output: "server"` or `output: "hybrid"` AND an adapter (Node, Vercel, Cloudflare, Netlify) — both are required.
Common Astro bugs
Real bug patterns from Astro apps, with the symptom you’ll see in a bug report and the fix that actually works.
Island state resets on navigation with view transitions
- Symptom
- A persistent header with a search input loses its value when navigating between pages.
- Fix
- Add `transition:persist` on the element AND on the framework wrapper. View transitions only persist marked elements.
<SearchInput client:load transition:persist="search" />Environment variables undefined in client islands
- Symptom
- `import.meta.env.MY_KEY` is undefined when called from a hydrated island.
- Fix
- Astro env vars are scoped by prefix — `PUBLIC_*` are exposed to client, everything else is server-only. Rename to `PUBLIC_MY_KEY`.
Markdown component imports work in .md but not in .mdx
- Symptom
- `import` at the top of an MDX file fails to resolve.
- Fix
- MDX in Astro requires `@astrojs/mdx` integration AND component imports must be inside the frontmatter, not at the top of the file body.
Setup
# Install BugMojo from the Chrome Web Store — works on every Astro adapterBugMojo vs alternatives
The honest comparison — where BugMojo wins, and where another tool might serve you better.
| Capability | BugMojo | View source / browser DevTools |
|---|---|---|
| See the pre-hydration HTML the user got | ✅ | ✅ view source |
| See the post-hydration DOM | ✅ | ✅ DevTools |
| See the moment hydration happened | ✅ replay | ❌ |
| Capture islands' client console errors | ✅ | ✅ live only |
| Shareable replay link | ✅ | ❌ |
Frequently asked questions
Sources
- Astro client directives reference — docs.astro.build (2025)