ReplacementSwap buggy in Astro 5? #279

claus · 2025-04-29T05:49:21Z

claus
Apr 29, 2025

I'm not 100% sure if this is a problem with ReplacementSwap, Astro, or me.

Let me start with an example. Consider an Astro layout that looks roughly like this:

<html>
  <head>
    <ClientRouter />
    <ReplacementSwap />
  </head>
  <body>
    <Header />
    <main data-vtbot-replace="main">
      <slot />
    </main>
  </body>
</html>

Here, instead of swapping the entire <body> we are using ReplacementSwap to only swap the <main> element. <Header> can't get detached from DOM because it has to maintain state. <body>, <Header> and other children of <body> besides <main> are left untouched during the swap.

This works fine as long as script and style imports stay in the <head>. ClientRouter's (or ReplacementSwap's) swap algorithm properly merges the outgoing with the incoming <head> contents. However, since Astro 5, script imports can be anywhere in the <body> and style imports seem to appear in the <body> as well. <body> children other than <main> do not get swapped, so if those elements happen to be new script and style imports.. those are never merged in, leading to missing styles and interactivity.

So in practice i have a situation that looks like this:

Outgoing page, Route A:

<body>
  <script type="module" src="/_astro/ROUTE-A-bundle.js" data-astro-exec></script>
  <link rel="stylesheet" href="/_astro/ROUTE-A-bundle.css">
  <Header />
  <main data-vtbot-replace="main">
    <!-- Outgoing page content -->
  </main>
</body>

Incoming page, Route B:

<body>
  <script type="module" src="/_astro/ROUTE-B-bundle.js" data-astro-exec></script>
  <link rel="stylesheet" href="/_astro/ROUTE-B-bundle.css">
  <Header />
  <main data-vtbot-replace="main">
    <!-- Incoming page content -->
  </main>
</body>

Only <main> is swapped (apart from <head> contents). Script and style includes (Route B bundles) in the incoming page's <body> are ignored, the resulting page will still have the Route A bundles.

Is there a fix for that? Am i doing something wrong?

martrapp · 2025-04-29T08:32:24Z

martrapp
Apr 29, 2025
Maintainer

Hi @claus 👋

Good to hear from you again!

I was actually pretty surprised myself by some of the changes in 5.0 around scripts and styles. The most unexpected part for me was that the new script processing finally triggered optimizations that had been around for a while but never kicked in. Especially the fact that scripts were being inlined when that had never happened before forced us to make some adjustments to our client router.

From what I understand, you want to swap just the <main> element, but you also have page-specific scripts and styles in the body that should be replaced as well.

How are those stylesheets being created on your end? especially the ones that are not inside <main> or <head>? Does the issue show in dev and prod? I would really like to understand that part better so I can give more helpful advice. Do you have a repo link, or could you send me a zip of the project?

Adding data-vtbot-replace attributes to the styles might not work, as I assume that they won't pair up 1-to-1 on the pages. I would try to move the styles into the <head> or into <main>.

Here are a few things you might try:

If you "import" stylesheets, they should go into the head automatically.
<style> elements of components should end up inside main
In my main layout, I usually have a named slot inside the where I can drop in styles and scripts. That works well if the component structure is simple.
Fryuni has a tool that lets you teleport HTML into the (or anywhere else): https://inox-tools.fryuni.dev/portal-gun

Long story short, I would really love to take a look at your actual project if that is possible. Would you be up for that?

3 replies

claus Apr 30, 2025
Author

Hey! 👋🏻

So it turns out that the problem was located between chair and keyboard as per usual, but this was quite a curious issue.

Those scripts and link rel stylesheets (mostly the latter) in the body are bundles generated by Astro (or Vite?) in the build process. They should go into the head, but ended up in the body.

The reason, as it turns out, was that i put something in the head that doesn't belong there. I didn't disclose that in my OP, because i thought it was irrelevant. Here's my Layout in a bit more detail:

<html>
  <head>
    <ClientRouter />
    <ReplacementSwap />
    <Lenis />
    <Parallax />
    <Reveals />
    <IconDefs />
  </head>
  <body>
    <Header />
    <main data-vtbot-replace="main">
      <slot />
    </main>
  </body>
</html>

I had some additional stuff in the head, mostly to initialize some fancy pants effects. However there's also <IconDefs> which is not a script at all but a SVG component. Which, being renderable content, definitely doesn't belong in the head. Browsers seem to automatically move the SVG and every sibling element that follows it (?!) into the body. Siblings are the generated CSS bundles.

Once i moved <IconDefs> into the body, the CSS bundles stayed in the head, and all was fine 🤷

<html>
  <head>
    <ClientRouter />
    <ReplacementSwap />
    <Lenis />
    <Parallax />
    <Reveals />
  </head>
  <body>
    <Header />
    <main data-vtbot-replace="main">
      <slot />
    </main>
    <IconDefs /> <!-- ← moved down here -->
  </body>
</html>

martrapp Apr 30, 2025
Maintainer

Hi @claus

What a thorough and well-done analysis! It all fits together perfectly.

I can confirm that Astro automatically closes the tag as soon as it encounters an element that belongs in the . It basically has a little “bag” for head content that it eventually wants to close so it can start streaming HTML to the browser (this also applies for SSG). Everything that comes after that naturally ends up in the body.

Thanks so much for analyzing and sharing!

claus Apr 30, 2025
Author

What a thorough and well-done analysis! It all fits together perfectly.

Thanks and yeah

I can confirm that Astro automatically closes the tag as soon as it encounters an element that belongs in the . It basically has a little “bag” for head content that it eventually wants to close so it can start streaming HTML to the browser (this also applies for SSG). Everything that comes after that naturally ends up in the body.

Oooooh wow yeah that's exactly what i'm seeing. But wait, how does that work in SSG builds? Do you know? My dist/client/index.html definitely has both the SVG and the CSS in <head>, and that's also exactly what arrives from the server. When exactly does Astro intervene?

Thanks so much for analyzing and sharing!

np, it's a fun little puzzle :)

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

ReplacementSwap buggy in Astro 5? #279

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{editor}}'s edit

{{editor}}'s edit

Uh oh!

Replies: 1 comment 3 replies

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{editor}}'s edit

{{editor}}'s edit

Uh oh!

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{title}}

Uh oh!

Select a reply

Uh oh!

Uh oh!

ReplacementSwap buggy in Astro 5? #279

Uh oh!

Uh oh!

claus Apr 29, 2025

Replies: 1 comment · 3 replies

Uh oh!

martrapp Apr 29, 2025 Maintainer

Uh oh!

Uh oh!

claus Apr 30, 2025 Author

Uh oh!

martrapp Apr 30, 2025 Maintainer

Uh oh!

claus Apr 30, 2025 Author

claus
Apr 29, 2025

Replies: 1 comment 3 replies

martrapp
Apr 29, 2025
Maintainer

claus Apr 30, 2025
Author

martrapp Apr 30, 2025
Maintainer

claus Apr 30, 2025
Author