vike-lite-react 1.0.0

package/README.md

@@ -0,0 +1,148 @@
+# vike-lite-react
+
+The official React integration for `vike-lite`. It provides seamless Server-Side Rendering (SSR), Static Site Generation (SSG), and client hydration out of the box, with a focus on minimalism and performance.
+
+### ⚙️ Install
+You need to install both `vike-lite-react` and the official Vite plugin for React (`@vitejs/plugin-react`).
+
+```sh
+# npm
+npm install -D vike-lite-react @vitejs/plugin-react
+npm install react react-dom
+
+# pnpm
+pnpm add -D vike-lite-react @vitejs/plugin-react
+pnpm add react react-dom
+
+# yarn
+yarn add -D vike-lite-react @vitejs/plugin-react
+yarn add react react-dom
+```
+
+### ⚙️ Vite Plugin
+
+```ts
+// vite.config.ts
+import type { UserConfig } from 'vite'
+import vikeLite from 'vike-lite/vite'
+import vikeLiteReact from 'vike-lite-react/vite'
+
+export default {
+  plugins: [
+    vikeLite(),
+    vikeLiteReact({
+      // Default is `true` that enables React Hydration
+      // Set to `false` for Client Takeover (SPA mode)
+      hydration: true,
+      // Advanced: pass options directly to the underlying @vitejs/plugin-react
+      react: {
+        babel: {
+          plugins: [
+            // e.g. add custom babel plugins
+          ]
+        }
+      }
+    })
+  ]
+} satisfies UserConfig
+```
+
+| Option | Type | Default | Description
+| - | - | - | -
+| `hydration` | `boolean` | `true` | When `true`, the server renders the page to HTML and the client hydrates it (`hydrateRoot`). When `false`, the client discards the server-rendered HTML on load and mounts a fresh tree (`createRoot`) — useful for highly interactive pages where paying the hydration-mismatch tax isn't worth it.
+| `react` | `Options` (from `@vitejs/plugin-react`) | `{}` | Passed through to the underlying `@vitejs/plugin-react` instance. Use this for `jsxImportSource` (e.g. Emotion), custom Babel plugins, or `jsxRuntime: 'classic'`.
+
+### 🪝 Hooks
+
+#### `useData`
+Access the data fetched by your `+data` functions directly inside your React components.
+```tsx
+// /pages/+Page.tsx
+import { useData } from 'vike-lite-react'
+
+type MyData = {
+  title: string
+}
+
+export default function Page() {
+  const [data, setData] = useData<MyData>()
+
+  return (
+    <div>
+      <h1>{data.title}</h1>
+      <button onClick={() => setData(prev => ({ ...prev, title: 'Updated Title!' }))}>
+        Update Data
+      </button>
+    </div>
+  )
+}
+```
+
+> 💡 **Note:** Like `vike-lite-solid`, the `useData` hook in `vike-lite-react` returns a tuple `[data, setData]`, letting you mutate the route data locally without needing an extra state manager.
+
+#### `usePageContext`
+Access the current page context, including URL parameters, original pathname, and route information.
+```tsx
+// /pages/+Page.tsx
+import { usePageContext } from 'vike-lite-react'
+
+export function Page() {
+  const pageContext = usePageContext()
+
+  return (
+    <div>
+      <p>Current Path: <strong>{pageContext.urlPathname}</strong></p>
+    </div>
+  )
+}
+```
+
+#### `useHydrated`
+Detect whether the application has successfully hydrated on the client. Essential for wrapping client-only libraries (like chart tools or window-dependent logic) to avoid SSR hydration mismatches.
+
+```tsx
+// /pages/+Page.tsx
+import { useHydrated } from 'vike-lite-react'
+import ClientOnlyChart from './Chart'
+
+export function Page() {
+  const hydrated = useHydrated()
+
+  return (
+    <div>
+      <h1>Statistics</h1>
+      {hydrated ? <ClientOnlyChart /> : <p>Loading chart…</p>}
+    </div>
+  )
+}
+```
+
+#### `useUrl`
+```tsx
+// /pages/+Page.tsx
+import { useUrl } from 'vike-lite-react'
+
+export function Page() {
+  const url = useUrl()
+
+  return (
+    <div>
+      <p>Current Query Parameter "myQueryParam": <strong>{url.searchParams.get('myQueryParam')}</strong></p>
+    </div>
+  )
+}
+```
+
+### Differences: `vike-react` vs `vike-lite-react`
+Why choose `vike-lite`? It's built to be as minimal and fast as possible. Here are the main architectural differences regarding the React integration:
+
+| **Feature** | `vike-react` | `vike-lite-react` | **Why it matters**
+| - | - | - | -
+| **Reactivity Architecture** | _Single Source of Truth_ | _Separation of Concerns_ | `vike-lite-react` keeps page data (`pageContext`) and the active UI (`view`: Page/Layout/Head) as two separate `useState` atoms, so a data update doesn't force React to re-resolve which components are mounted, and vice versa.
+| **Accessibility (A11y)** | _Not_ handled by default | _Automatic_ handled | After a client-side navigation, `vike-lite-react` moves the focus to `#root`. This significantly improves UX for keyboard navigation and screen readers.
+| `useData()` **Hook** | `getter` only | `[getter, setter]` | `vike-lite-react` allows you to mutate the route data locally without needing other state managers.
+| URL parsed | manual `new URL(pageContext.urlOriginal)` | [useUrl()](#useurl) | A dedicated hook, consistent with `vike-lite-solid`.
+
+---
+
+This project is licensed under the [MIT License](../../LICENSE).

package/dist/index.d.mts

@@ -0,0 +1,20 @@
+import { PageContext, PageContextClient } from "vike-lite";
+//#region src/hooks/useData.d.ts
+declare function useData<Data = unknown>(): [Data, (updater: Data | ((prev: Data) => Data)) => void];
+//#endregion
+//#region src/hooks/usePageContext.d.ts
+declare function usePageContext(): PageContext;
+//#endregion
+//#region src/hooks/useHydrated.d.ts
+declare function useHydrated(): boolean;
+//#endregion
+//#region src/hooks/useUrl.d.ts
+declare function useUrl(): URL;
+//#endregion
+//#region src/hooks/globalContext.d.ts
+interface PageContextValue {
+  pageContext: PageContextClient;
+  setPageContext: (updater: (prev: PageContextClient) => PageContextClient) => void;
+}
+//#endregion
+export { type PageContextValue, useData, useHydrated, usePageContext, useUrl };

package/dist/index.mjs

@@ -0,0 +1,40 @@
+import { createContext, useCallback, useContext, useEffect, useMemo, useState } from "react";
+//#region src/hooks/globalContext.tsx
+const KEY = "__vike_lite_react_context__";
+const g = globalThis;
+if (!Object.hasOwn(g, KEY)) g[KEY] = createContext(null);
+const PageContextReactContext = g[KEY];
+//#endregion
+//#region src/hooks/useData.tsx
+function useData() {
+	const ctx = useContext(PageContextReactContext);
+	if (!ctx) throw new Error("useData() must be called inside a page rendered by vike-lite-react");
+	return [ctx.pageContext.data, useCallback((updater) => {
+		ctx.setPageContext((prev) => ({
+			...prev,
+			data: typeof updater === "function" ? updater(prev.data) : updater
+		}));
+	}, [ctx])];
+}
+//#endregion
+//#region src/hooks/usePageContext.tsx
+function usePageContext() {
+	const ctx = useContext(PageContextReactContext);
+	if (!ctx) throw new Error("usePageContext() must be called inside a page rendered by vike-lite-react");
+	return ctx.pageContext;
+}
+//#endregion
+//#region src/hooks/useHydrated.tsx
+function useHydrated() {
+	const [hydrated, setHydrated] = useState(false);
+	useEffect(() => setHydrated(true), []);
+	return hydrated;
+}
+//#endregion
+//#region src/hooks/useUrl.tsx
+function useUrl() {
+	const pageContext = usePageContext();
+	return useMemo(() => new URL(pageContext.urlOriginal), [pageContext.urlOriginal]);
+}
+//#endregion
+export { useData, useHydrated, usePageContext, useUrl };

package/dist/vite.d.mts

@@ -0,0 +1,17 @@
+import { Options } from "@vitejs/plugin-react";
+import { Plugin } from "vite";
+//#region src/vite-plugin.d.ts
+interface VikeLiteReactOptions {
+  /**
+   * Enable client hydration (SSR + hydrate) or full client takeover (SPA mode).
+   * @default true
+   */
+  hydration?: boolean;
+  /**
+   * Advanced: pass options directly to the underlying @vitejs/plugin-react.
+   */
+  react?: Options;
+}
+declare function vikeLiteReact(options?: VikeLiteReactOptions): Plugin[];
+//#endregion
+export { VikeLiteReactOptions, vikeLiteReact as default };

package/dist/vite.mjs

@@ -0,0 +1,24 @@
+import react from "@vitejs/plugin-react";
+//#region src/vite-plugin.ts
+function vikeLiteReact(options = {}) {
+	const { hydration = true, react: reactOptions } = options;
+	const virtualConfigId = "virtual:vike-lite/config";
+	const virtualRendererId = "virtual:vike-lite/renderer";
+	const resolvedVirtualConfigId = "\0virtual:vike-lite/config";
+	const resolvedVirtualRendererId = "\0virtual:vike-lite/renderer";
+	const adapter = {
+		name: "vike-lite-react",
+		enforce: "pre",
+		resolveId(id) {
+			if (id === virtualConfigId) return resolvedVirtualConfigId;
+			if (id === virtualRendererId) return resolvedVirtualRendererId;
+		},
+		load(id) {
+			if (id === resolvedVirtualConfigId) return `export const hydration = ${JSON.stringify(hydration)};`;
+			if (id === resolvedVirtualRendererId) return "export const onRenderHtml = () => import('vike-lite-react/__internal/server/onRenderHtml');export const onRenderClient = () => import('vike-lite-react/__internal/client/onRenderClient');";
+		}
+	};
+	return [...react(reactOptions), adapter];
+}
+//#endregion
+export { vikeLiteReact as default };

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "vike-lite-react",
+  "version": "1.0.0",
+  "license": "MIT",
+  "type": "module",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs"
+    },
+    "./vite": {
+      "types": "./dist/vite.d.mts",
+      "import": "./dist/vite.mjs"
+    },
+    "./__internal/client/onRenderClient": {
+      "types": "./src/__internal/client/onRenderClient.tsx",
+      "import": "./src/__internal/client/onRenderClient.tsx"
+    },
+    "./__internal/server/onRenderHtml": {
+      "types": "./src/__internal/server/onRenderHtml.tsx",
+      "import": "./src/__internal/server/onRenderHtml.tsx"
+    }
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/node-ecosystem/vike-lite-react.git"
+  },
+  "homepage": "https://github.com/node-ecosystem/vike-lite-react#readme",
+  "bugs": {
+    "url": "https://github.com/node-ecosystem/vike-lite-react/issues"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "tsc": "tsc --noEmit",
+    "build": "tsdown"
+  },
+  "devDependencies": {
+    "@types/node": "^26.1.1",
+    "@types/react": "^19.2.17",
+    "@types/react-dom": "^19.2.3",
+    "@vitejs/plugin-react": "^6.0.3",
+    "react": "^19.2.7",
+    "react-dom": "^19.2.7",
+    "tsdown": "^0.22.5",
+    "vike-lite": "1.13.0",
+    "vite": "^8.1.4"
+  },
+  "peerDependencies": {
+    "@vitejs/plugin-react": ">=6",
+    "react": "*",
+    "react-dom": "*",
+    "vike-lite": "*",
+    "vite": ">=8"
+  },
+  "engines": {
+    "node": "^20.19.0 || >=22.12.0"
+  }
+}