@live-react-islands/vite-plugin-ssr 0.1.0

package/README.md

@@ -0,0 +1,455 @@
+# Live React Islands
+
+**React-powered interactive islands** inside Phoenix LiveView. Harness the NPM ecosystem with server-driven state, real-time streams and zero-lag forms + SSR.
+
+![Banner](docs/repository-open-graph.png)
+
+## Why Live React Islands?
+
+**The best of both worlds!** ✨
+
+Phoenix LiveView is excellent for server-driven UIs, but sometimes you need the rich interactivity of React for specific components. Live React Islands lets you:
+
+- Use React components as "islands" within your LiveView templates
+- Maintain server-side state in Elixir while rendering in React
+- Send events from React to Elixir and push props back
+- Use forms and streams in React with dedicated hooks
+- Share global state across multiple islands
+- Optionally server-side render for faster loads, SEO and no flicker
+
+## Comparison
+
+Choose Live React Islands when you need rich, interactive React components without giving up LiveView’s server-driven simplicity.
+
+| Feature                | LiveView Only                              | LiveView + Alpine    | Live React Islands (this)              | Pure SPA (Next.js/Vite) |
+| :--------------------- | :----------------------------------------- | :------------------- | :------------------------------------- | :---------------------- |
+| **UI Ecosystem**       | Limited (HEEX/Custom)                      | Small (Alpine kits)  | **Infinite (NPM/React)**               | **Infinite (NPM)**      |
+| **Interactivity**      | Server-Roundtrip (JS hooks for edge cases) | Simple Client-side   | **High-Fidelity / Fluid**              | High-Fidelity / Fluid   |
+| **State Management**   | Single (Server)                            | Fragmented           | **Single (Server-Led)**                | Dual (API + Client)     |
+| **Initial Load / SEO** | Instant                                    | Instant              | **Instant (SSR-enabled)**              | Slow / Complex SSR      |
+| **JS Bundle Size**     | ~0kb (Core only)                           | Small (+15kb)        | **Large (React: ~100–150 kB gzipped)** | Large                   |
+| **Developer Speed**    | Very High                                  | High (until complex) | **High (Asset Reuse)**                 | Low (API Plumbing)      |
+| **Component Logic**    | Elixir Only                                | Mixed (Strings)      | **JSX (Encapsulated)**                 | JSX                     |
+| **Complexity Ceiling** | Struggles with app-like complexity         | Hits wall on "State" | **High**                               | Very High               |
+
+## When NOT to Use Live React Islands
+
+- If your UI is mostly static or CRUD-heavy, plain LiveView is simpler and faster.
+- If you only need light client-side behavior (toggles, dropdowns), LiveView + Alpine may be sufficient.
+- If your application requires full offline support or heavy client-side state, a traditional SPA may be a better fit.
+
+## Installation
+
+### Elixir
+
+Add to your `mix.exs`:
+
+```elixir
+def deps do
+  [
+    {:live_react_islands, "~> 0.1.0"},
+    # For development SSR (optional):
+    {:live_react_islands_ssr_vite, "~> 0.1.0", only: :dev},
+    # For production SSR (optional):
+    {:live_react_islands_ssr_deno, "~> 0.1.0", only: :prod}
+  ]
+end
+```
+
+### JavaScript
+
+```bash
+npm install @live-react-islands/core
+# For development SSR (optional):
+npm install --save-dev @live-react-islands/vite-plugin-ssr
+```
+
+## Quick Start
+
+### 1. Create a React Component
+
+```jsx
+// src/islands/Counter.jsx
+const Counter = ({ count, title, pushEvent }) => {
+  return (
+    <div>
+      <h2>{title}</h2>
+      <p>Count: {count}</p>
+      <button onClick={() => pushEvent("increment", {})}>+1</button>
+    </div>
+  );
+};
+
+export default Counter;
+```
+
+### 2. Set Up the LiveView Hooks
+
+```jsx
+// src/islands/index.js
+export default { Counter: () => import("./Counter") };
+```
+
+Islands can be lazy loaded to only load the JS used on the page.
+
+```jsx
+// src/main.jsx
+import { createHooks } from "@live-react-islands/core";
+import islands from "./islands";
+
+const islandHooks = createHooks({ islands });
+
+// Add to your LiveSocket
+let liveSocket = new LiveSocket("/live", Socket, {
+  hooks: { ...islandHooks },
+});
+```
+
+### 3. Create an Elixir Component
+
+```elixir
+defmodule MyAppWeb.Components.CounterIsland do
+  use LiveReactIslands.Component,
+    component: "Counter",
+    props: %{count: 0, title: "My Counter"}
+
+  def handle_event("increment", _params, socket) do
+    new_count = socket.assigns.count + 1
+    {:noreply, update_prop(socket, :count, new_count)}
+  end
+end
+```
+
+### 4. Use in Your LiveView
+
+```elixir
+defmodule MyAppWeb.CounterLive do
+  use MyAppWeb, :live_view
+  use LiveReactIslands.LiveView
+
+  def render(assigns) do
+    ~H"""
+    <.live_component module={MyAppWeb.Components.CounterIsland} id="counter-1" />
+    """
+  end
+end
+```
+
+## How It Works
+
+**React components receive these props automatically:**
+
+| Prop                 | Description                       |
+| -------------------- | --------------------------------- |
+| `id`                 | The island's unique identifier    |
+| `pushEvent`          | Function to send events to Elixir |
+| All defined props    | Current values from Elixir        |
+| All consumed globals | Current global state values       |
+
+## Features
+
+### Props
+
+Define props with default values. Props can be set from the template or updated from event handlers:
+
+```elixir
+use LiveReactIslands.Component,
+  component: "Counter",
+  props: %{count: 0, title: "Default Title"}
+```
+
+**Elixir components can override `init/2` for dynamic initialization:**
+
+```elixir
+def init(assigns, socket) do
+  # Called once on mount, before SSR and first render
+  socket
+  |> update_prop(:computed, compute_value(assigns))
+end
+```
+
+**Updating props from Elixir:**
+
+```elixir
+def handle_event("increment", _, socket) do
+  {:noreply, update_prop(socket, :count, socket.assigns.count + 1)}
+end
+```
+
+**Passing props from templates:**
+
+```heex
+<.live_component module={CounterIsland} id="counter-1" title="Custom Title" />
+```
+
+Once a prop is set from outside the component any `update_prop` call on it will raise an error to prevent a nasty set of bugs. To just initialize the component use `init_[prop]` to set the value once and then the component takes over.
+
+```heex
+<.live_component module={CounterIsland} id="counter-1" init_count={5} />
+```
+
+### Events
+
+Send events from React to Elixir using `pushEvent`:
+
+```jsx
+// React
+<button onClick={() => pushEvent("save", { data: formData })}>Save</button>
+```
+
+```elixir
+# Elixir
+def handle_event("save", %{"data" => data}, socket) do
+  # Handle the event
+  {:noreply, socket}
+end
+```
+
+### Global State
+
+Share state across multiple islands. When a global changes, all islands that use it automatically rerender.
+
+**Set up in your LiveView:**
+
+```elixir
+defmodule MyAppWeb.DashboardLive do
+  use MyAppWeb, :live_view
+  use LiveReactIslands.LiveView, expose_globals: [:user, :theme]
+
+  def mount(_params, session, socket) do
+    {:ok, assign(socket, user: get_user(session), theme: "light")}
+  end
+end
+```
+
+**Consume in your island:**
+
+```elixir
+use LiveReactIslands.Component,
+  component: "Header",
+  props: %{},
+  globals: [:user, :theme]
+```
+
+**Optional globals** (won't error if not set):
+
+```elixir
+globals: [:user?]  # The ? suffix makes it optional
+```
+
+The globals are passed as props to your React component:
+
+```jsx
+const Header = ({ user, theme }) => (
+  <header className={theme}>Welcome, {user.name}</header>
+);
+```
+
+### Forms with Server Validation
+
+Build forms with React UI and Elixir/Ecto validation. Input is collected client side with zero typing latency and send to Elixir for validation. Errors from the changeset get pushed back to React.
+
+The `useForm` hook implements a "Validation Lock" pattern: Updates are versioned and `isValid` will only be true until the server confirms the current form state is valid.
+
+**Elixir component:**
+
+```elixir
+defmodule MyAppWeb.Components.ContactFormIsland do
+  use LiveReactIslands.Component,
+    component: "ContactForm",
+    props: %{form: %{}}
+
+  alias MyApp.Contact
+
+  def init(_assigns, socket) do
+    changeset = Contact.changeset(%Contact{}, %{})
+    socket |> init_form(:form, changeset)
+  end
+
+  def handle_form(:validate, :form, attrs, socket) do
+    changeset = Contact.changeset(%Contact{}, attrs)
+    {:noreply, update_form(socket, :form, changeset)}
+  end
+
+  def handle_form(:submit, :form, attrs, socket) do
+    case Contact.create(attrs) do
+      {:ok, _contact} ->
+        {:noreply, init_form(socket, :form, Contact.changeset(%Contact{}, %{}))}
+      {:error, changeset} ->
+        {:noreply, update_form(socket, :form, changeset)}
+    end
+  end
+end
+```
+
+**React component:**
+
+```jsx
+import { useForm } from "@live-react-islands/core";
+
+const ContactForm = ({ form, pushEvent }) => {
+  const {
+    getFieldProps,
+    getError,
+    isRequired,
+    isTouched,
+    handleSubmit,
+    isValid,
+  } = useForm(form, pushEvent);
+
+  return (
+    <form onSubmit={handleSubmit}>
+      <input {...getFieldProps("name")} />
+      {isTouched("name") && getError("name") && (
+        <span className="error">{getError("name")}</span>
+      )}
+
+      <input {...getFieldProps("email")} type="email" />
+      {isTouched("email") && getError("email") && (
+        <span className="error">{getError("email")}</span>
+      )}
+
+      <button type="submit" disabled={!isValid}>
+        Submit
+      </button>
+    </form>
+  );
+};
+```
+
+**`useForm` returns:**
+
+| Property                | Description                                           |
+| ----------------------- | ----------------------------------------------------- |
+| `values`                | Current form values                                   |
+| `errors`                | Validation errors by field                            |
+| `touched`               | Fields the user has interacted with                   |
+| `getFieldProps(name)`   | Props to spread on inputs (`value`, `onChange`, etc.) |
+| `getError(name)`        | First error message for a field                       |
+| `isRequired(name)`      | Whether a field is required                           |
+| `isTouched(name)`       | Whether user has modified this field                  |
+| `setField(name, value)` | Programmatically set a field value                    |
+| `handleSubmit`          | Form submit handler                                   |
+| `reset()`               | Reset form to server values                           |
+| `isSyncing`             | True while waiting for server validation              |
+| `isValid`               | True only when synced AND server says valid           |
+
+### Streams
+
+Stream data to React components for real-time updates like feeds, chat, or infinite scrolling:
+
+**Define a stream prop:**
+
+```elixir
+use LiveReactIslands.Component,
+  component: "MessageList",
+  props: %{
+    messages: {:stream, default: []}
+  }
+```
+
+**Push stream events from Elixir:**
+
+```elixir
+# Insert new item (prepends by default)
+socket |> stream_insert(:messages, %{id: 1, text: "Hello"})
+
+# Update existing item
+socket |> stream_update(:messages, %{id: 1, text: "Hello, edited"})
+
+# Delete an item
+socket |> stream_delete(:messages, 1)
+
+# Reset the entire stream
+socket |> stream_reset(:messages)
+```
+
+**Consume in React:**
+
+```jsx
+import { useStream } from "@live-react-islands/core";
+
+const MessageList = ({ messages: messagesHandle }) => {
+  const messages = useStream(messagesHandle, { limit: 100 });
+
+  return (
+    <ul>
+      {messages.map((msg) => (
+        <li key={msg.id}>{msg.text}</li>
+      ))}
+    </ul>
+  );
+};
+```
+
+### Shared Context
+
+Islands using `:none` (default) or `:overwrite` SSR strategies render into a shared React root via portals. This enables powerful patterns like drag-and-drop between islands, shared state managers, or animation libraries that need to coordinate across components.
+
+**Wrap all islands in a shared context:**
+
+```jsx
+// src/main.jsx
+import { createHooks } from "@live-react-islands/core";
+import { DndProvider } from "react-beautiful-dnd";
+import islands from "./islands";
+
+const SharedContextProvider = ({ children }) => (
+  <DndProvider backend={HTML5Backend}>{children}</DndProvider>
+);
+
+const islandHooks = createHooks({
+  islands,
+  SharedContextProvider,
+});
+```
+
+Now all your islands can participate in drag-and-drop with each other, even though they're scattered across your LiveView template.
+
+> **Note:** Islands using `:hydrate_root` SSR strategy have their own isolated React root and do not participate in the shared context. Use `:overwrite` or `:none` if you need context sharing between islands.
+
+### Server-Side Rendering (SSR)
+
+SSR improves initial page load performance by rendering React components on the server.
+
+```elixir
+use LiveReactIslands.Component,
+  component: "Counter",
+  props: %{count: 0},
+  ssr_strategy: :overwrite  # or :hydrate_root or :none (default)
+```
+
+| Strategy        | Shared Root | Best For                                                                |
+| --------------- | ----------- | ----------------------------------------------------------------------- |
+| `:none`         | Yes         | Interactive components where initial render doesn't matter              |
+| `:overwrite`    | Yes         | Most islands, especially when you need cross-island context (e.g., DnD) |
+| `:hydrate_root` | No          | Large islands where you want to avoid the overwrite flash               |
+
+> ⚠️ SSR is optional. Many islands work perfectly without it. Enable SSR when initial paint, SEO, or perceived performance matter.
+
+See the **[SSR Guide](https://github.com/dcza/live-react-islands/blob/main/docs/SSR.md)** for complete setup instructions, caching strategies, and custom renderer implementation.
+
+## Requirements
+
+- Elixir >= 1.14
+- Phoenix LiveView >= 1.0
+- React 18 or 19
+- Any JavaScript bundler (built-in SSR plugin for Vite)
+
+### Running Examples
+
+```bash
+cd examples/vite-example
+mix deps.get
+yarn install
+yarn dev
+mix phx.server  # in another terminal
+```
+
+## Contributing
+
+See [CONTRIBUTING.md](https://github.com/dcza/live-react-islands/blob/main/CONTRIBUTING.md) for development setup and guidelines.
+
+## License
+
+MIT License - see [LICENSE](https://github.com/dcza/live-react-islands/blob/main/LICENSE) for details.

package/dist/index.d.mts

@@ -0,0 +1,41 @@
+import { Plugin } from 'vite';
+
+interface LiveReactIslandsSSROptions {
+    /**
+     * Path to the SSR entry file (relative to project root)
+     * This file should call exposeSSR() from @live-react-islands/core/ssr
+     * @default "./src/ssr.js"
+     */
+    ssrEntry?: string;
+    /**
+     * SSR endpoint path
+     * @default "/__ssr"
+     */
+    endpoint?: string;
+}
+/**
+ * Vite plugin for LiveReactIslands SSR development server
+ *
+ * Adds a middleware endpoint that handles SSR requests from Elixir's ViteRenderer.
+ * Uses Vite's HMR-enabled module loading for instant feedback during development.
+ *
+ * @example
+ * ```ts
+ * // vite.config.js
+ * import { defineConfig } from "vite";
+ * import react from "@vitejs/plugin-react";
+ * import liveReactIslandsSSR from "@live-react-islands/vite-plugin-ssr";
+ *
+ * export default defineConfig({
+ *   plugins: [
+ *     react(),
+ *     liveReactIslandsSSR({
+ *       ssrEntry: "./src/ssr.js",
+ *     }),
+ *   ],
+ * });
+ * ```
+ */
+declare function liveReactIslandsSSR(options?: LiveReactIslandsSSROptions): Plugin;
+
+export { type LiveReactIslandsSSROptions, liveReactIslandsSSR as default };

package/dist/index.d.ts

@@ -0,0 +1,41 @@
+import { Plugin } from 'vite';
+
+interface LiveReactIslandsSSROptions {
+    /**
+     * Path to the SSR entry file (relative to project root)
+     * This file should call exposeSSR() from @live-react-islands/core/ssr
+     * @default "./src/ssr.js"
+     */
+    ssrEntry?: string;
+    /**
+     * SSR endpoint path
+     * @default "/__ssr"
+     */
+    endpoint?: string;
+}
+/**
+ * Vite plugin for LiveReactIslands SSR development server
+ *
+ * Adds a middleware endpoint that handles SSR requests from Elixir's ViteRenderer.
+ * Uses Vite's HMR-enabled module loading for instant feedback during development.
+ *
+ * @example
+ * ```ts
+ * // vite.config.js
+ * import { defineConfig } from "vite";
+ * import react from "@vitejs/plugin-react";
+ * import liveReactIslandsSSR from "@live-react-islands/vite-plugin-ssr";
+ *
+ * export default defineConfig({
+ *   plugins: [
+ *     react(),
+ *     liveReactIslandsSSR({
+ *       ssrEntry: "./src/ssr.js",
+ *     }),
+ *   ],
+ * });
+ * ```
+ */
+declare function liveReactIslandsSSR(options?: LiveReactIslandsSSROptions): Plugin;
+
+export { type LiveReactIslandsSSROptions, liveReactIslandsSSR as default };

package/dist/index.js

@@ -0,0 +1,97 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  default: () => liveReactIslandsSSR
+});
+module.exports = __toCommonJS(index_exports);
+function liveReactIslandsSSR(options = {}) {
+  const ssrEntry = options.ssrEntry || "./src/ssr.js";
+  const endpoint = options.endpoint || "/__ssr";
+  return {
+    name: "live-react-islands-ssr",
+    configureServer(server) {
+      server.middlewares.use(async (req, res, next) => {
+        if (req.method !== "POST" || req.url !== endpoint) {
+          return next();
+        }
+        try {
+          const chunks = [];
+          for await (const chunk of req) {
+            chunks.push(Buffer.from(chunk));
+          }
+          const body = JSON.parse(Buffer.concat(chunks).toString());
+          const { component, id, props, globals, strategy } = body;
+          if (!component || !id) {
+            res.statusCode = 400;
+            res.setHeader("Content-Type", "application/json");
+            res.end(
+              JSON.stringify({
+                error: "Missing required fields: component and id"
+              })
+            );
+            return;
+          }
+          await server.ssrLoadModule(ssrEntry);
+          const ssrModule = globalThis.SSR_MODULE;
+          if (!ssrModule || !ssrModule.renderSSRIsland) {
+            res.statusCode = 500;
+            res.setHeader("Content-Type", "application/json");
+            res.end(
+              JSON.stringify({
+                error: `SSR module not found. Make sure ${ssrEntry} calls exposeSSR() from @live-react-islands/core/ssr`
+              })
+            );
+            return;
+          }
+          const html = ssrModule.renderSSRIsland(
+            component,
+            id,
+            props || {},
+            globals || {},
+            strategy || "overwrite"
+          );
+          console.log(
+            `[live-react-islands-ssr] Rendered ${component} (id: ${id}, strategy: ${strategy})`,
+            { props, globals }
+          );
+          res.statusCode = 200;
+          res.setHeader("Content-Type", "application/json");
+          res.end(JSON.stringify({ html }));
+        } catch (error) {
+          console.error("[live-react-islands-ssr] Error rendering component:", error);
+          res.statusCode = 500;
+          res.setHeader("Content-Type", "application/json");
+          res.end(
+            JSON.stringify({
+              error: error.message || "Unknown error during SSR",
+              stack: error.stack
+            })
+          );
+        }
+      });
+      console.log(
+        `[live-react-islands-ssr] SSR endpoint available at ${endpoint}`
+      );
+    }
+  };
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["import type { Plugin, ViteDevServer } from \"vite\";\n\nexport interface LiveReactIslandsSSROptions {\n  /**\n   * Path to the SSR entry file (relative to project root)\n   * This file should call exposeSSR() from @live-react-islands/core/ssr\n   * @default \"./src/ssr.js\"\n   */\n  ssrEntry?: string;\n\n  /**\n   * SSR endpoint path\n   * @default \"/__ssr\"\n   */\n  endpoint?: string;\n}\n\ninterface SSRRequest {\n  component: string;\n  id: string;\n  props: Record<string, any>;\n  globals: Record<string, any>;\n  strategy?: \"hydrate_root\" | \"overwrite\";\n}\n\ninterface SSRModule {\n  renderSSRIsland: (\n    component: string,\n    id: string,\n    props: Record<string, any>,\n    globals: Record<string, any>,\n    strategy: \"hydrate_root\" | \"overwrite\"\n  ) => string;\n}\n\n/**\n * Vite plugin for LiveReactIslands SSR development server\n *\n * Adds a middleware endpoint that handles SSR requests from Elixir's ViteRenderer.\n * Uses Vite's HMR-enabled module loading for instant feedback during development.\n *\n * @example\n * ```ts\n * // vite.config.js\n * import { defineConfig } from \"vite\";\n * import react from \"@vitejs/plugin-react\";\n * import liveReactIslandsSSR from \"@live-react-islands/vite-plugin-ssr\";\n *\n * export default defineConfig({\n *   plugins: [\n *     react(),\n *     liveReactIslandsSSR({\n *       ssrEntry: \"./src/ssr.js\",\n *     }),\n *   ],\n * });\n * ```\n */\nexport default function liveReactIslandsSSR(\n  options: LiveReactIslandsSSROptions = {}\n): Plugin {\n  const ssrEntry = options.ssrEntry || \"./src/ssr.js\";\n  const endpoint = options.endpoint || \"/__ssr\";\n\n  return {\n    name: \"live-react-islands-ssr\",\n\n    configureServer(server: ViteDevServer) {\n      server.middlewares.use(async (req, res, next) => {\n        // Only handle POST requests to our SSR endpoint\n        if (req.method !== \"POST\" || req.url !== endpoint) {\n          return next();\n        }\n\n        try {\n          // Parse request body\n          const chunks: Buffer[] = [];\n          for await (const chunk of req) {\n            chunks.push(Buffer.from(chunk));\n          }\n          const body = JSON.parse(Buffer.concat(chunks).toString());\n\n          const { component, id, props, globals, strategy } = body as SSRRequest;\n\n          // Validate request\n          if (!component || !id) {\n            res.statusCode = 400;\n            res.setHeader(\"Content-Type\", \"application/json\");\n            res.end(\n              JSON.stringify({\n                error: \"Missing required fields: component and id\",\n              })\n            );\n            return;\n          }\n\n          // Load the SSR module using Vite's HMR-enabled loader\n          // This ensures we always get the latest version during development\n          await server.ssrLoadModule(ssrEntry);\n\n          // Access the global SSR_MODULE exposed by exposeSSR()\n          const ssrModule = (globalThis as any).SSR_MODULE as\n            | SSRModule\n            | undefined;\n\n          if (!ssrModule || !ssrModule.renderSSRIsland) {\n            res.statusCode = 500;\n            res.setHeader(\"Content-Type\", \"application/json\");\n            res.end(\n              JSON.stringify({\n                error: `SSR module not found. Make sure ${ssrEntry} calls exposeSSR() from @live-react-islands/core/ssr`,\n              })\n            );\n            return;\n          }\n\n          // Render the component using strategy-aware function\n          const html = ssrModule.renderSSRIsland(\n            component,\n            id,\n            props || {},\n            globals || {},\n            strategy || \"overwrite\"\n          );\n\n          console.log(\n            `[live-react-islands-ssr] Rendered ${component} (id: ${id}, strategy: ${strategy})`,\n            { props, globals }\n          );\n\n          // Return the rendered HTML\n          res.statusCode = 200;\n          res.setHeader(\"Content-Type\", \"application/json\");\n          res.end(JSON.stringify({ html }));\n        } catch (error: any) {\n          console.error(\"[live-react-islands-ssr] Error rendering component:\", error);\n\n          res.statusCode = 500;\n          res.setHeader(\"Content-Type\", \"application/json\");\n          res.end(\n            JSON.stringify({\n              error: error.message || \"Unknown error during SSR\",\n              stack: error.stack,\n            })\n          );\n        }\n      });\n\n      console.log(\n        `[live-react-islands-ssr] SSR endpoint available at ${endpoint}`\n      );\n    },\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AA0De,SAAR,oBACL,UAAsC,CAAC,GAC/B;AACR,QAAM,WAAW,QAAQ,YAAY;AACrC,QAAM,WAAW,QAAQ,YAAY;AAErC,SAAO;AAAA,IACL,MAAM;AAAA,IAEN,gBAAgB,QAAuB;AACrC,aAAO,YAAY,IAAI,OAAO,KAAK,KAAK,SAAS;AAE/C,YAAI,IAAI,WAAW,UAAU,IAAI,QAAQ,UAAU;AACjD,iBAAO,KAAK;AAAA,QACd;AAEA,YAAI;AAEF,gBAAM,SAAmB,CAAC;AAC1B,2BAAiB,SAAS,KAAK;AAC7B,mBAAO,KAAK,OAAO,KAAK,KAAK,CAAC;AAAA,UAChC;AACA,gBAAM,OAAO,KAAK,MAAM,OAAO,OAAO,MAAM,EAAE,SAAS,CAAC;AAExD,gBAAM,EAAE,WAAW,IAAI,OAAO,SAAS,SAAS,IAAI;AAGpD,cAAI,CAAC,aAAa,CAAC,IAAI;AACrB,gBAAI,aAAa;AACjB,gBAAI,UAAU,gBAAgB,kBAAkB;AAChD,gBAAI;AAAA,cACF,KAAK,UAAU;AAAA,gBACb,OAAO;AAAA,cACT,CAAC;AAAA,YACH;AACA;AAAA,UACF;AAIA,gBAAM,OAAO,cAAc,QAAQ;AAGnC,gBAAM,YAAa,WAAmB;AAItC,cAAI,CAAC,aAAa,CAAC,UAAU,iBAAiB;AAC5C,gBAAI,aAAa;AACjB,gBAAI,UAAU,gBAAgB,kBAAkB;AAChD,gBAAI;AAAA,cACF,KAAK,UAAU;AAAA,gBACb,OAAO,mCAAmC,QAAQ;AAAA,cACpD,CAAC;AAAA,YACH;AACA;AAAA,UACF;AAGA,gBAAM,OAAO,UAAU;AAAA,YACrB;AAAA,YACA;AAAA,YACA,SAAS,CAAC;AAAA,YACV,WAAW,CAAC;AAAA,YACZ,YAAY;AAAA,UACd;AAEA,kBAAQ;AAAA,YACN,qCAAqC,SAAS,SAAS,EAAE,eAAe,QAAQ;AAAA,YAChF,EAAE,OAAO,QAAQ;AAAA,UACnB;AAGA,cAAI,aAAa;AACjB,cAAI,UAAU,gBAAgB,kBAAkB;AAChD,cAAI,IAAI,KAAK,UAAU,EAAE,KAAK,CAAC,CAAC;AAAA,QAClC,SAAS,OAAY;AACnB,kBAAQ,MAAM,uDAAuD,KAAK;AAE1E,cAAI,aAAa;AACjB,cAAI,UAAU,gBAAgB,kBAAkB;AAChD,cAAI;AAAA,YACF,KAAK,UAAU;AAAA,cACb,OAAO,MAAM,WAAW;AAAA,cACxB,OAAO,MAAM;AAAA,YACf,CAAC;AAAA,UACH;AAAA,QACF;AAAA,MACF,CAAC;AAED,cAAQ;AAAA,QACN,sDAAsD,QAAQ;AAAA,MAChE;AAAA,IACF;AAAA,EACF;AACF;","names":[]}

package/dist/index.mjs

@@ -0,0 +1,76 @@
+// src/index.ts
+function liveReactIslandsSSR(options = {}) {
+  const ssrEntry = options.ssrEntry || "./src/ssr.js";
+  const endpoint = options.endpoint || "/__ssr";
+  return {
+    name: "live-react-islands-ssr",
+    configureServer(server) {
+      server.middlewares.use(async (req, res, next) => {
+        if (req.method !== "POST" || req.url !== endpoint) {
+          return next();
+        }
+        try {
+          const chunks = [];
+          for await (const chunk of req) {
+            chunks.push(Buffer.from(chunk));
+          }
+          const body = JSON.parse(Buffer.concat(chunks).toString());
+          const { component, id, props, globals, strategy } = body;
+          if (!component || !id) {
+            res.statusCode = 400;
+            res.setHeader("Content-Type", "application/json");
+            res.end(
+              JSON.stringify({
+                error: "Missing required fields: component and id"
+              })
+            );
+            return;
+          }
+          await server.ssrLoadModule(ssrEntry);
+          const ssrModule = globalThis.SSR_MODULE;
+          if (!ssrModule || !ssrModule.renderSSRIsland) {
+            res.statusCode = 500;
+            res.setHeader("Content-Type", "application/json");
+            res.end(
+              JSON.stringify({
+                error: `SSR module not found. Make sure ${ssrEntry} calls exposeSSR() from @live-react-islands/core/ssr`
+              })
+            );
+            return;
+          }
+          const html = ssrModule.renderSSRIsland(
+            component,
+            id,
+            props || {},
+            globals || {},
+            strategy || "overwrite"
+          );
+          console.log(
+            `[live-react-islands-ssr] Rendered ${component} (id: ${id}, strategy: ${strategy})`,
+            { props, globals }
+          );
+          res.statusCode = 200;
+          res.setHeader("Content-Type", "application/json");
+          res.end(JSON.stringify({ html }));
+        } catch (error) {
+          console.error("[live-react-islands-ssr] Error rendering component:", error);
+          res.statusCode = 500;
+          res.setHeader("Content-Type", "application/json");
+          res.end(
+            JSON.stringify({
+              error: error.message || "Unknown error during SSR",
+              stack: error.stack
+            })
+          );
+        }
+      });
+      console.log(
+        `[live-react-islands-ssr] SSR endpoint available at ${endpoint}`
+      );
+    }
+  };
+}
+export {
+  liveReactIslandsSSR as default
+};
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["import type { Plugin, ViteDevServer } from \"vite\";\n\nexport interface LiveReactIslandsSSROptions {\n  /**\n   * Path to the SSR entry file (relative to project root)\n   * This file should call exposeSSR() from @live-react-islands/core/ssr\n   * @default \"./src/ssr.js\"\n   */\n  ssrEntry?: string;\n\n  /**\n   * SSR endpoint path\n   * @default \"/__ssr\"\n   */\n  endpoint?: string;\n}\n\ninterface SSRRequest {\n  component: string;\n  id: string;\n  props: Record<string, any>;\n  globals: Record<string, any>;\n  strategy?: \"hydrate_root\" | \"overwrite\";\n}\n\ninterface SSRModule {\n  renderSSRIsland: (\n    component: string,\n    id: string,\n    props: Record<string, any>,\n    globals: Record<string, any>,\n    strategy: \"hydrate_root\" | \"overwrite\"\n  ) => string;\n}\n\n/**\n * Vite plugin for LiveReactIslands SSR development server\n *\n * Adds a middleware endpoint that handles SSR requests from Elixir's ViteRenderer.\n * Uses Vite's HMR-enabled module loading for instant feedback during development.\n *\n * @example\n * ```ts\n * // vite.config.js\n * import { defineConfig } from \"vite\";\n * import react from \"@vitejs/plugin-react\";\n * import liveReactIslandsSSR from \"@live-react-islands/vite-plugin-ssr\";\n *\n * export default defineConfig({\n *   plugins: [\n *     react(),\n *     liveReactIslandsSSR({\n *       ssrEntry: \"./src/ssr.js\",\n *     }),\n *   ],\n * });\n * ```\n */\nexport default function liveReactIslandsSSR(\n  options: LiveReactIslandsSSROptions = {}\n): Plugin {\n  const ssrEntry = options.ssrEntry || \"./src/ssr.js\";\n  const endpoint = options.endpoint || \"/__ssr\";\n\n  return {\n    name: \"live-react-islands-ssr\",\n\n    configureServer(server: ViteDevServer) {\n      server.middlewares.use(async (req, res, next) => {\n        // Only handle POST requests to our SSR endpoint\n        if (req.method !== \"POST\" || req.url !== endpoint) {\n          return next();\n        }\n\n        try {\n          // Parse request body\n          const chunks: Buffer[] = [];\n          for await (const chunk of req) {\n            chunks.push(Buffer.from(chunk));\n          }\n          const body = JSON.parse(Buffer.concat(chunks).toString());\n\n          const { component, id, props, globals, strategy } = body as SSRRequest;\n\n          // Validate request\n          if (!component || !id) {\n            res.statusCode = 400;\n            res.setHeader(\"Content-Type\", \"application/json\");\n            res.end(\n              JSON.stringify({\n                error: \"Missing required fields: component and id\",\n              })\n            );\n            return;\n          }\n\n          // Load the SSR module using Vite's HMR-enabled loader\n          // This ensures we always get the latest version during development\n          await server.ssrLoadModule(ssrEntry);\n\n          // Access the global SSR_MODULE exposed by exposeSSR()\n          const ssrModule = (globalThis as any).SSR_MODULE as\n            | SSRModule\n            | undefined;\n\n          if (!ssrModule || !ssrModule.renderSSRIsland) {\n            res.statusCode = 500;\n            res.setHeader(\"Content-Type\", \"application/json\");\n            res.end(\n              JSON.stringify({\n                error: `SSR module not found. Make sure ${ssrEntry} calls exposeSSR() from @live-react-islands/core/ssr`,\n              })\n            );\n            return;\n          }\n\n          // Render the component using strategy-aware function\n          const html = ssrModule.renderSSRIsland(\n            component,\n            id,\n            props || {},\n            globals || {},\n            strategy || \"overwrite\"\n          );\n\n          console.log(\n            `[live-react-islands-ssr] Rendered ${component} (id: ${id}, strategy: ${strategy})`,\n            { props, globals }\n          );\n\n          // Return the rendered HTML\n          res.statusCode = 200;\n          res.setHeader(\"Content-Type\", \"application/json\");\n          res.end(JSON.stringify({ html }));\n        } catch (error: any) {\n          console.error(\"[live-react-islands-ssr] Error rendering component:\", error);\n\n          res.statusCode = 500;\n          res.setHeader(\"Content-Type\", \"application/json\");\n          res.end(\n            JSON.stringify({\n              error: error.message || \"Unknown error during SSR\",\n              stack: error.stack,\n            })\n          );\n        }\n      });\n\n      console.log(\n        `[live-react-islands-ssr] SSR endpoint available at ${endpoint}`\n      );\n    },\n  };\n}\n"],"mappings":";AA0De,SAAR,oBACL,UAAsC,CAAC,GAC/B;AACR,QAAM,WAAW,QAAQ,YAAY;AACrC,QAAM,WAAW,QAAQ,YAAY;AAErC,SAAO;AAAA,IACL,MAAM;AAAA,IAEN,gBAAgB,QAAuB;AACrC,aAAO,YAAY,IAAI,OAAO,KAAK,KAAK,SAAS;AAE/C,YAAI,IAAI,WAAW,UAAU,IAAI,QAAQ,UAAU;AACjD,iBAAO,KAAK;AAAA,QACd;AAEA,YAAI;AAEF,gBAAM,SAAmB,CAAC;AAC1B,2BAAiB,SAAS,KAAK;AAC7B,mBAAO,KAAK,OAAO,KAAK,KAAK,CAAC;AAAA,UAChC;AACA,gBAAM,OAAO,KAAK,MAAM,OAAO,OAAO,MAAM,EAAE,SAAS,CAAC;AAExD,gBAAM,EAAE,WAAW,IAAI,OAAO,SAAS,SAAS,IAAI;AAGpD,cAAI,CAAC,aAAa,CAAC,IAAI;AACrB,gBAAI,aAAa;AACjB,gBAAI,UAAU,gBAAgB,kBAAkB;AAChD,gBAAI;AAAA,cACF,KAAK,UAAU;AAAA,gBACb,OAAO;AAAA,cACT,CAAC;AAAA,YACH;AACA;AAAA,UACF;AAIA,gBAAM,OAAO,cAAc,QAAQ;AAGnC,gBAAM,YAAa,WAAmB;AAItC,cAAI,CAAC,aAAa,CAAC,UAAU,iBAAiB;AAC5C,gBAAI,aAAa;AACjB,gBAAI,UAAU,gBAAgB,kBAAkB;AAChD,gBAAI;AAAA,cACF,KAAK,UAAU;AAAA,gBACb,OAAO,mCAAmC,QAAQ;AAAA,cACpD,CAAC;AAAA,YACH;AACA;AAAA,UACF;AAGA,gBAAM,OAAO,UAAU;AAAA,YACrB;AAAA,YACA;AAAA,YACA,SAAS,CAAC;AAAA,YACV,WAAW,CAAC;AAAA,YACZ,YAAY;AAAA,UACd;AAEA,kBAAQ;AAAA,YACN,qCAAqC,SAAS,SAAS,EAAE,eAAe,QAAQ;AAAA,YAChF,EAAE,OAAO,QAAQ;AAAA,UACnB;AAGA,cAAI,aAAa;AACjB,cAAI,UAAU,gBAAgB,kBAAkB;AAChD,cAAI,IAAI,KAAK,UAAU,EAAE,KAAK,CAAC,CAAC;AAAA,QAClC,SAAS,OAAY;AACnB,kBAAQ,MAAM,uDAAuD,KAAK;AAE1E,cAAI,aAAa;AACjB,cAAI,UAAU,gBAAgB,kBAAkB;AAChD,cAAI;AAAA,YACF,KAAK,UAAU;AAAA,cACb,OAAO,MAAM,WAAW;AAAA,cACxB,OAAO,MAAM;AAAA,YACf,CAAC;AAAA,UACH;AAAA,QACF;AAAA,MACF,CAAC;AAED,cAAQ;AAAA,QACN,sDAAsD,QAAQ;AAAA,MAChE;AAAA,IACF;AAAA,EACF;AACF;","names":[]}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@live-react-islands/vite-plugin-ssr",
+  "version": "0.1.0",
+  "description": "Vite plugin for LiveReactIslands SSR development server",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "clean": "rm -rf dist",
+    "prepublishOnly": "cp ../../../README.md ./"
+  },
+  "keywords": [
+    "vite",
+    "vite-plugin",
+    "ssr",
+    "liveview",
+    "react",
+    "islands"
+  ],
+  "author": "David Czaplinski",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/dcza/live-react-islands.git",
+    "directory": "packages/js/vite-plugin-ssr"
+  },
+  "peerDependencies": {
+    "vite": "^5.0.0 || ^6.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.6.3",
+    "vite": "^6.0.7"
+  }
+}

package/src/index.ts

@@ -0,0 +1,154 @@
+import type { Plugin, ViteDevServer } from "vite";
+
+export interface LiveReactIslandsSSROptions {
+  /**
+   * Path to the SSR entry file (relative to project root)
+   * This file should call exposeSSR() from @live-react-islands/core/ssr
+   * @default "./src/ssr.js"
+   */
+  ssrEntry?: string;
+
+  /**
+   * SSR endpoint path
+   * @default "/__ssr"
+   */
+  endpoint?: string;
+}
+
+interface SSRRequest {
+  component: string;
+  id: string;
+  props: Record<string, any>;
+  globals: Record<string, any>;
+  strategy?: "hydrate_root" | "overwrite";
+}
+
+interface SSRModule {
+  renderSSRIsland: (
+    component: string,
+    id: string,
+    props: Record<string, any>,
+    globals: Record<string, any>,
+    strategy: "hydrate_root" | "overwrite"
+  ) => string;
+}
+
+/**
+ * Vite plugin for LiveReactIslands SSR development server
+ *
+ * Adds a middleware endpoint that handles SSR requests from Elixir's ViteRenderer.
+ * Uses Vite's HMR-enabled module loading for instant feedback during development.
+ *
+ * @example
+ * ```ts
+ * // vite.config.js
+ * import { defineConfig } from "vite";
+ * import react from "@vitejs/plugin-react";
+ * import liveReactIslandsSSR from "@live-react-islands/vite-plugin-ssr";
+ *
+ * export default defineConfig({
+ *   plugins: [
+ *     react(),
+ *     liveReactIslandsSSR({
+ *       ssrEntry: "./src/ssr.js",
+ *     }),
+ *   ],
+ * });
+ * ```
+ */
+export default function liveReactIslandsSSR(
+  options: LiveReactIslandsSSROptions = {}
+): Plugin {
+  const ssrEntry = options.ssrEntry || "./src/ssr.js";
+  const endpoint = options.endpoint || "/__ssr";
+
+  return {
+    name: "live-react-islands-ssr",
+
+    configureServer(server: ViteDevServer) {
+      server.middlewares.use(async (req, res, next) => {
+        // Only handle POST requests to our SSR endpoint
+        if (req.method !== "POST" || req.url !== endpoint) {
+          return next();
+        }
+
+        try {
+          // Parse request body
+          const chunks: Buffer[] = [];
+          for await (const chunk of req) {
+            chunks.push(Buffer.from(chunk));
+          }
+          const body = JSON.parse(Buffer.concat(chunks).toString());
+
+          const { component, id, props, globals, strategy } = body as SSRRequest;
+
+          // Validate request
+          if (!component || !id) {
+            res.statusCode = 400;
+            res.setHeader("Content-Type", "application/json");
+            res.end(
+              JSON.stringify({
+                error: "Missing required fields: component and id",
+              })
+            );
+            return;
+          }
+
+          // Load the SSR module using Vite's HMR-enabled loader
+          // This ensures we always get the latest version during development
+          await server.ssrLoadModule(ssrEntry);
+
+          // Access the global SSR_MODULE exposed by exposeSSR()
+          const ssrModule = (globalThis as any).SSR_MODULE as
+            | SSRModule
+            | undefined;
+
+          if (!ssrModule || !ssrModule.renderSSRIsland) {
+            res.statusCode = 500;
+            res.setHeader("Content-Type", "application/json");
+            res.end(
+              JSON.stringify({
+                error: `SSR module not found. Make sure ${ssrEntry} calls exposeSSR() from @live-react-islands/core/ssr`,
+              })
+            );
+            return;
+          }
+
+          // Render the component using strategy-aware function
+          const html = ssrModule.renderSSRIsland(
+            component,
+            id,
+            props || {},
+            globals || {},
+            strategy || "overwrite"
+          );
+
+          console.log(
+            `[live-react-islands-ssr] Rendered ${component} (id: ${id}, strategy: ${strategy})`,
+            { props, globals }
+          );
+
+          // Return the rendered HTML
+          res.statusCode = 200;
+          res.setHeader("Content-Type", "application/json");
+          res.end(JSON.stringify({ html }));
+        } catch (error: any) {
+          console.error("[live-react-islands-ssr] Error rendering component:", error);
+
+          res.statusCode = 500;
+          res.setHeader("Content-Type", "application/json");
+          res.end(
+            JSON.stringify({
+              error: error.message || "Unknown error during SSR",
+              stack: error.stack,
+            })
+          );
+        }
+      });
+
+      console.log(
+        `[live-react-islands-ssr] SSR endpoint available at ${endpoint}`
+      );
+    },
+  };
+}