feat(1.x): accept a clientOnly loader that resolves to the component (#2347)

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

Author: lxsmnsyc

.changeset/client-only-named-export.md

@@ -0,0 +1,11 @@
+---
+"@solidjs/start": patch
+---
+
+Let a `clientOnly` loader resolve to the component itself, so a named export works without wrapping it in `{ default }`:
+
+```tsx
+const Chart = clientOnly(() => import("./chart").then(({ Chart }) => Chart));
+```
+
+Destructuring the export inside the loader also lets the bundler leave the module's other exports out of the chunk.

apps/tests/cypress/e2e/client-only.cy.ts

@@ -0,0 +1,12 @@
+describe("clientOnly", () => {
+  it("renders a named export when the loader resolves to the component", () => {
+    cy.request("/client-only/named").then(response => {
+      expect(response.body).to.contain("CLIENT_ONLY_FALLBACK");
+      expect(response.body).not.to.contain("CLIENT_ONLY_NAMED_EXPORT_RENDERED");
+    });
+
+    cy.visit("/client-only/named");
+    cy.get("#client-only-named").contains("CLIENT_ONLY_NAMED_EXPORT_RENDERED");
+    cy.get("#client-only-fallback").should("not.exist");
+  });
+});

apps/tests/src/routes/client-only/_named.tsx

@@ -0,0 +1,8 @@
+export function NamedClientOnly() {
+  return <p id="client-only-named">CLIENT_ONLY_NAMED_EXPORT_RENDERED</p>;
+}
+
+// Never imported through clientOnly, so it should stay out of the client bundle.
+export function UnusedClientOnly() {
+  return <p>CLIENT_ONLY_UNUSED_EXPORT_MARKER</p>;
+}

apps/tests/src/routes/client-only/named.tsx

@@ -0,0 +1,9 @@
+import { clientOnly } from "@solidjs/start";
+
+const NamedClientOnly = clientOnly(() =>
+  import("./_named").then(({ NamedClientOnly }) => NamedClientOnly)
+);
+
+export default function ClientOnlyNamed() {
+  return <NamedClientOnly fallback={<p id="client-only-fallback">CLIENT_ONLY_FALLBACK</p>} />;
+}

apps/tests/src/routes/treeshaking/client-only.test.ts

@@ -0,0 +1,20 @@
+import { readFile, readdir } from "node:fs/promises";
+import path from "node:path";
+import { describe, expect, it } from "vitest";
+
+// clientOnly(() => import("./_named").then(({ NamedClientOnly }) => NamedClientOnly))
+// reads the export inside the loader, so the bundler can leave the module's other
+// exports out of the client bundle (#2064).
+describe("clientOnly with a named export", () => {
+  it("bundles only the export the loader reads", async () => {
+    const buildDir = path.resolve(process.cwd(), ".vinxi/build/client/_build/assets");
+    const files = (await readdir(buildDir)).filter(file => file.endsWith(".js"));
+    const contents = await Promise.all(
+      files.map(file => readFile(path.join(buildDir, file), "utf-8"))
+    );
+    const client = contents.join("\n");
+
+    expect(client).toContain("CLIENT_ONLY_NAMED_EXPORT_RENDERED");
+    expect(client).not.toContain("CLIENT_ONLY_UNUSED_EXPORT_MARKER");
+  });
+});

packages/start/src/shared/clientOnly.tsx

@@ -4,14 +4,29 @@ import { createMemo, createSignal, onMount, sharedConfig, splitProps, untrack }
 import { isServer } from "solid-js/web";
 
 /**
+ * What a `clientOnly` loader can resolve to: a module with a default export,
+ * or the component itself.
+ */
+type ClientOnlyModule<T> = T | { default: T };
+
+/**
+ * Renders a component only on the client. The loader can resolve to a module
+ * with a default export, or to the component itself, which also works for a
+ * named export:
+ *
+ * ```tsx
+ * const Map = clientOnly(() => import("./map"));
+ * const Chart = clientOnly(() => import("./chart").then(({ Chart }) => Chart));
+ * ```
+ *
+ * Destructuring the export inside the loader, as in the second example, lets
+ * the bundler leave the module's other exports out of the chunk.
  *
  * Read more: https://docs.solidjs.com/solid-start/reference/client/client-only
  */
 // not using Suspense
 export default function clientOnly<T extends Component<any>>(
-  fn: () => Promise<{
-    default: T;
-  }>,
+  fn: () => Promise<ClientOnlyModule<T>>,
   options: { lazy?: boolean } = {}
 ) {
   if (isServer) return (props: ComponentProps<T> & { fallback?: JSX.Element }) => props.fallback;
@@ -34,11 +49,10 @@ export default function clientOnly<T extends Component<any>>(
   };
 }
 
-function load<T>(
-  fn: () => Promise<{
-    default: T;
-  }>,
-  setComp: Setter<T>
+function load<T extends Component<any>>(
+  fn: () => Promise<ClientOnlyModule<T>>,
+  setComp: Setter<T | undefined>
 ) {
-  fn().then(m => setComp(() => m.default));
+  // A module namespace object is never a function, and a component always is.
+  fn().then(m => setComp(() => (typeof m === "function" ? m : m.default)));
 }