fix: warn when Partial with append/prepend mode is missing key prop (#3738)

## Summary
- Adds a `console.warn` during SSR when a `<Partial>` uses
`mode="append"` or `mode="prepend"` without a `key` prop
- Without a key, Preact cannot correctly reconcile prepended/appended
children, leading to subtle rendering bugs
- No warning for `mode="replace"` (default) since keys aren't required
there

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: bartlomieju

docs/latest/advanced/partials.md

@@ -156,7 +156,7 @@ shops for example.
 export default function AddToCartPartial() {
   return (
     <>
-      <Partial name="cart-items" mode="append">
+      <Partial name="cart-items" mode="append" key={newItem.id}>
         {/* Render the new cart item here */}
       </Partial>
       <Partial name="total-price">
@@ -187,7 +187,7 @@ export default function LogView() {
   const lines = getNewLogLines();
 
   return (
-    <Partial name="logs-list" mode="append">
+    <Partial name="logs-list" mode="append" key={lines[0]}>
       {lines.map((line) => {
         return <li key={line}>{line}</li>;
       })}
@@ -196,8 +196,10 @@ export default function LogView() {
 }
 ```
 
-> [info]: When picking the `prepend` or `append` mode, make sure to add keys to
-> the elements.
+> [warn]: When using `prepend` or `append` mode, you **must** add a `key` prop
+> to the `<Partial>` component. Without it, Preact cannot distinguish new
+> children from existing ones, leading to subtle rendering bugs. Fresh will log
+> a warning if it detects a missing key on an append/prepend partial.
 
 ## Bypassing or disabling Partials
 

packages/fresh/src/runtime/server/preact_hooks.ts

@@ -194,6 +194,19 @@ options[OptionsType.DIFF] = (vnode) => {
             `<Partial> components cannot be used inside islands.`,
           );
         }
+
+        const mode = (vnode.props as PartialProps).mode;
+        if (
+          (mode === "append" || mode === "prepend") &&
+          vnode.key == null
+        ) {
+          // deno-lint-ignore no-console
+          console.warn(
+            `<Partial name="${name}" mode="${mode}"> is missing a "key" prop. ` +
+              `Without a key, Preact cannot correctly reconcile ${mode}ed children. ` +
+              `Add a unique key to fix this.`,
+          );
+        }
       } else if (
         !PATCHED.has(vnode)
       ) {

packages/fresh/tests/partials_test.tsx

@@ -15,6 +15,7 @@ import {
 } from "./test_utils.tsx";
 import { SelfCounter } from "./fixtures_islands/SelfCounter.tsx";
 import { expect } from "@std/expect";
+import { assertSpyCalls, spy } from "@std/testing/mock";
 import { PartialInIsland } from "./fixtures_islands/PartialInIsland.tsx";
 import { FakeServer } from "../src/test_utils.ts";
 import { JsonIsland } from "./fixtures_islands/JsonIsland.tsx";
@@ -2775,3 +2776,91 @@ Deno.test({
     });
   },
 });
+
+Deno.test({
+  name: "partials - warns when append/prepend missing key",
+  fn: async () => {
+    const app = testApp()
+      .get("/", (ctx) => {
+        return ctx.render(
+          <Doc>
+            <Partial name="no-key-append" mode="append">
+              <p>content</p>
+            </Partial>
+            <Partial name="no-key-prepend" mode="prepend">
+              <p>content</p>
+            </Partial>
+          </Doc>,
+        );
+      });
+
+    const warnSpy = spy(console, "warn");
+    try {
+      const server = new FakeServer(app.handler());
+      await server.get("/");
+      assertSpyCalls(warnSpy, 2);
+      expect(String(warnSpy.calls[0].args[0])).toContain("no-key-append");
+      expect(String(warnSpy.calls[0].args[0])).toContain("append");
+      expect(String(warnSpy.calls[1].args[0])).toContain("no-key-prepend");
+      expect(String(warnSpy.calls[1].args[0])).toContain("prepend");
+    } finally {
+      warnSpy.restore();
+    }
+  },
+});
+
+Deno.test({
+  name: "partials - no warning when append/prepend has key",
+  fn: async () => {
+    const app = testApp()
+      .get("/", (ctx) => {
+        return ctx.render(
+          <Doc>
+            <Partial name="keyed-append" mode="append" key="a">
+              <p>content</p>
+            </Partial>
+            <Partial name="keyed-prepend" mode="prepend" key="b">
+              <p>content</p>
+            </Partial>
+          </Doc>,
+        );
+      });
+
+    const warnSpy = spy(console, "warn");
+    try {
+      const server = new FakeServer(app.handler());
+      await server.get("/");
+      assertSpyCalls(warnSpy, 0);
+    } finally {
+      warnSpy.restore();
+    }
+  },
+});
+
+Deno.test({
+  name: "partials - no warning for replace mode without key",
+  fn: async () => {
+    const app = testApp()
+      .get("/", (ctx) => {
+        return ctx.render(
+          <Doc>
+            <Partial name="replace-no-key" mode="replace">
+              <p>content</p>
+            </Partial>
+            <Partial name="default-no-key">
+              <p>content</p>
+            </Partial>
+          </Doc>,
+        );
+      });
+
+    const warnSpy = spy(console, "warn");
+    try {
+      const server = new FakeServer(app.handler());
+      await server.get("/");
+      assertSpyCalls(warnSpy, 0);
+    } finally {
+      warnSpy.restore();
+    }
+  },
+});