feat: first draft of @hocuspocus/provide-react package

Author: janthurau

package-lock.json

@@ -0,0 +1,35 @@
+{
+	"name": "@hocuspocus/provider-react",
+	"version": "3.4.6-rc.2",
+	"description": "React bindings for Hocuspocus provider",
+	"homepage": "https://hocuspocus.dev",
+	"keywords": ["hocuspocus", "websocket", "provider", "react", "yjs"],
+	"license": "MIT",
+	"type": "module",
+	"main": "dist/hocuspocus-provider-react.cjs",
+	"module": "dist/hocuspocus-provider-react.esm.js",
+	"types": "dist/index.d.ts",
+	"exports": {
+		"source": {
+			"import": "./src/index.ts"
+		},
+		"default": {
+			"import": "./dist/hocuspocus-provider-react.esm.js",
+			"require": "./dist/hocuspocus-provider-react.cjs",
+			"types": "./dist/index.d.ts"
+		}
+	},
+	"files": ["src", "dist"],
+	"peerDependencies": {
+		"@hocuspocus/provider": "^3.4.6-rc.2",
+		"react": "^18.0.0 || ^19.0.0",
+		"yjs": "^13.6.8"
+	},
+	"devDependencies": {
+		"@types/react": "^18.0.0",
+		"react": "^18.0.0"
+	},
+	"repository": {
+		"url": "https://github.com/ueberdosis/hocuspocus"
+	}
+}

packages/provider-react/package.json

@@ -0,0 +1,63 @@
+import { HocuspocusProviderWebsocket } from "@hocuspocus/provider";
+import { useEffect, useMemo, useRef } from "react";
+
+import { HocuspocusContext } from "./context.ts";
+import type { HocuspocusProviderComponentProps } from "./types.ts";
+
+/**
+ * HocuspocusProviderComponent manages the WebSocket connection that is shared across all rooms.
+ *
+ * This component creates a single WebSocket connection that can be used by multiple
+ * HocuspocusRoom components, preventing connection overhead when switching between documents.
+ *
+ * @example
+ * ```tsx
+ * <HocuspocusProviderComponent url="ws://localhost:1234">
+ *   <HocuspocusRoom name="document-1">
+ *     <Editor />
+ *   </HocuspocusRoom>
+ * </HocuspocusProviderComponent>
+ * ```
+ */
+export function HocuspocusProviderComponent({
+	children,
+	url,
+	websocketProvider: externalWebsocketProvider,
+}: HocuspocusProviderComponentProps) {
+	const websocketRef = useRef<HocuspocusProviderWebsocket | null>(null);
+
+	// Create WebSocket provider once on mount
+	if (!websocketRef.current && !externalWebsocketProvider) {
+		websocketRef.current = new HocuspocusProviderWebsocket({
+			url: url ?? "",
+		});
+	}
+
+	const websocketProvider =
+		externalWebsocketProvider ??
+		(websocketRef.current as HocuspocusProviderWebsocket);
+
+	// Cleanup on unmount
+	useEffect(() => {
+		return () => {
+			// Only destroy if we created the websocket (not externally provided)
+			if (!externalWebsocketProvider && websocketRef.current) {
+				websocketRef.current.destroy();
+				websocketRef.current = null;
+			}
+		};
+	}, [externalWebsocketProvider]);
+
+	const contextValue = useMemo(
+		() => ({
+			websocketProvider,
+		}),
+		[websocketProvider],
+	);
+
+	return (
+		<HocuspocusContext.Provider value={contextValue}>
+			{children}
+		</HocuspocusContext.Provider>
+	);
+}

packages/provider-react/src/HocuspocusProviderComponent.tsx

@@ -0,0 +1,110 @@
+import { HocuspocusProvider } from "@hocuspocus/provider";
+import { useContext, useEffect, useMemo, useRef } from "react";
+
+import { HocuspocusContext, HocuspocusRoomContext } from "./context.ts";
+import type { HocuspocusRoomProps } from "./types.ts";
+
+/**
+ * HocuspocusRoom manages the connection to a specific document.
+ *
+ * It uses the shared WebSocket from HocuspocusProviderComponent and creates a document-specific
+ * provider that connects on mount and disconnects on unmount.
+ *
+ * This component handles React's StrictMode gracefully by using deferred destruction,
+ * preventing unnecessary reconnections during development double-mounts.
+ *
+ * @example
+ * ```tsx
+ * <HocuspocusProviderComponent url="ws://localhost:1234">
+ *   <HocuspocusRoom name="document-1">
+ *     <Editor />
+ *   </HocuspocusRoom>
+ * </HocuspocusProviderComponent>
+ * ```
+ */
+export function HocuspocusRoom({
+	children,
+	name,
+	document,
+	token,
+}: HocuspocusRoomProps) {
+	const hocuspocusContext = useContext(HocuspocusContext);
+
+	if (!hocuspocusContext) {
+		throw new Error(
+			"HocuspocusRoom must be used within a HocuspocusProviderComponent",
+		);
+	}
+
+	const { websocketProvider } = hocuspocusContext;
+
+	const providerRef = useRef<HocuspocusProvider | null>(null);
+	const destroyTimeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+	// Store current props in a ref to access in cleanup without triggering re-creation
+	const propsRef = useRef({ name, document, token });
+	propsRef.current = { name, document, token };
+
+	// Create or retrieve provider
+	// We use a ref to prevent recreation on every render
+	if (!providerRef.current) {
+		providerRef.current = new HocuspocusProvider({
+			name,
+			websocketProvider,
+			document,
+			token,
+		});
+	}
+
+	const provider = providerRef.current;
+
+	useEffect(() => {
+		// Cancel any pending destruction (handles StrictMode double-mount)
+		if (destroyTimeoutRef.current) {
+			clearTimeout(destroyTimeoutRef.current);
+			destroyTimeoutRef.current = null;
+		}
+
+		return () => {
+			// Deferred destruction - wait for potential remount in StrictMode
+			// Using setTimeout(0) allows React to remount before we destroy
+			destroyTimeoutRef.current = setTimeout(() => {
+				if (providerRef.current) {
+					providerRef.current.destroy();
+					providerRef.current = null;
+				}
+			}, 0);
+		};
+	}, []);
+
+	// Handle document name changes - need to recreate provider
+	useEffect(() => {
+		// Skip on initial mount since we already created the provider
+		if (
+			providerRef.current &&
+			providerRef.current.configuration.name !== name
+		) {
+			// Name changed, need to recreate provider
+			providerRef.current.destroy();
+			providerRef.current = new HocuspocusProvider({
+				name,
+				websocketProvider,
+				document: propsRef.current.document,
+				token: propsRef.current.token,
+			});
+		}
+	}, [name, websocketProvider]);
+
+	const contextValue = useMemo(
+		() => ({
+			provider,
+		}),
+		[provider],
+	);
+
+	return (
+		<HocuspocusRoomContext.Provider value={contextValue}>
+			{children}
+		</HocuspocusRoomContext.Provider>
+	);
+}