feat: Replace existing HTML meta tags

rschristian · rschristian · commit 3bb10f2eb93d · 2026-02-05T23:31:50.000-06:00
diff --git a/README.md b/README.md
@@ -79,7 +79,8 @@ export async function prerender(data) {
             // Sets the title for the current page: `<title>My cool page</title>`
             title: 'My cool page',
 
-            // Sets any additional elements you want injected into the `<head>`:
+            // Sets any additional elements you want injected into the `<head>`.
+            // `type: 'meta'` elements will replace existing matching tags in the input HTML:
             //   <link rel="stylesheet" href="foo.css">
             //   <meta property="og:title" content="Social media title">
             elements: new Set([
diff --git a/src/plugins/prerender-plugin.js b/src/plugins/prerender-plugin.js
@@ -464,7 +464,7 @@ export function prerenderPlugin({ prerenderScript, renderTarget, additionalPrere
                     body = result;
                 }
 
-                const htmlHead = htmlDoc.querySelector('head');
+                const htmlHead = /** @type {HTMLHeadElement} */ (htmlDoc.querySelector('head'));
                 if (htmlHead) {
                     if (head.title) {
                         const htmlTitle = htmlHead.querySelector('title');
@@ -481,13 +481,27 @@ export function prerenderPlugin({ prerenderScript, renderTarget, additionalPrere
                     }
 
                     if (head.elements) {
-                        // Inject HTML links at the end of <head> for any stylesheets injected during rendering of the page:
-                        htmlHead.insertAdjacentHTML(
-                            'beforeend',
-                            Array.from(
-                                new Set(Array.from(head.elements).map(serializeElement)),
-                            ).join('\n'),
-                        );
+                        for (const element of head.elements) {
+                            const serialized = serializeElement(element);
+
+                            if (element.type === 'meta') {
+                                const keys = Object.keys(element.props || {});
+                                if (keys.length) {
+                                    // We're going to (somewhat naively) assume that the first prop is
+                                    // a unique identifier for the tag
+                                    const key = keys[0];
+                                    const val = element.props[key];
+
+                                    const existing = htmlHead.querySelector(`meta[${key}="${val}"]`);
+                                    if (existing) {
+                                        existing.replaceWith(serialized);
+                                        continue;
+                                    }
+                                }
+                            }
+
+                            htmlHead.insertAdjacentHTML('beforeend', serialized);
+                        }
                     }
                 }
 
diff --git a/tests/fixtures/simple/index.html b/tests/fixtures/simple/index.html
@@ -1,7 +1,8 @@
 <!DOCTYPE html>
 <html lang="en">
     <head>
-        <meta charset="UTF-8" />
+        <meta charset="UTF-8">
+        <meta name="description" content="A simple web page with a prerendered script.">
     </head>
     <body>
         <script prerender type="module" src="/src/index.js"></script>
diff --git a/tests/prerender-api.test.js b/tests/prerender-api.test.js
@@ -116,4 +116,30 @@ test('Should support `head.elements` property', async () => {
     assert.match(prerenderedHtml, '<meta property="og:title" content="Social media title">');
 });
 
+test('Should support `head.elements` property replacing', async () => {
+    await loadFixture('simple', env);
+    await writeEntry(env.tmp.path, `
+        export async function prerender() {
+            return {
+                html: '<h1>Hello, World!</h1>',
+                head: {
+                    elements: new Set([
+                        { type: 'meta', props: { name: 'description', content: 'Foo' } },
+                    ]),
+                },
+            };
+        }
+    `);
+    await viteBuild(env.tmp.path);
+
+    const prerenderedHtml = await getOutputFile(env.tmp.path, 'index.html');
+    const matches = Array.from(
+        prerenderedHtml.matchAll(/<meta name="description"/g),
+        (m) => m[0]
+    );
+    assert.is(matches.length, 1);
+    assert.match(prerenderedHtml, '<meta name="description" content="Foo">');
+    assert.not.match(prerenderedHtml, '<meta name="description" content="A simple web page with a prerendered script.">');
+});
+
 test.run();
