Pitfall Preferences redcorsair

Astro Carousel Js Ssr Mismatch

astrojavascriptssrfrontend

Astro SSR Breaks Interactive JS Carousels

What Happened

Built an interactive attack results carousel on the AI Safety page using inline <script> tags with DOM manipulation (querySelector, event listeners, class toggling). The carousel worked in local dev but broke in production : navigation buttons didn’t respond, slides didn’t rotate.

Two fix attempts failed before abandoning the approach entirely:

  1. fix: Website improvements - carousel navigation (Jun 30 11:07)
  2. feat(website): Fix AI safety carousel and build out for-agents page (Jun 30 11:19)
  3. Final fix: fix: Replace broken carousel with working accordion (Jun 30 13:39)

Root Cause

See definitions/root-cause-analysis for the analytical framework. Specific cause: Astro’s SSR/static build model means inline scripts don’t reliably bind to DOM elements at the expected time. Event listeners attached in <script> tags can execute before the target elements exist in the DOM, or Astro’s island architecture can cause hydration mismatches where the JS references stale DOM nodes.

How to Avoid

In Astro, default to progressive enhancement: start with HTML/CSS that works without JS, then layer interactivity via Astro components with client:load or client:visible directives. Avoid raw inline <script> tags for anything that manipulates the DOM.

For the carousel specifically: replaced it with a pure CSS accordion (<details>/<summary> or CSS :target). Each attack result gets a clickable header. No JavaScript required, no hydration mismatch possible.