feat(react): add @superdoc-dev/react wrapper package

.github/workflows/ci-react.yml

@@ -0,0 +1,45 @@
+name: CI React
+
+permissions:
+  contents: read
+
+on:
+  pull_request:
+    paths:
+      - 'packages/react/**'
+  workflow_dispatch:
+
+concurrency:
+  group: ci-react-${{ github.event.pull_request.number }}
+  cancel-in-progress: true
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: pnpm/action-setup@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version-file: .nvmrc
+          cache: pnpm
+
+      - name: Install dependencies
+        run: pnpm install
+
+      - name: Build superdoc (dependency)
+        run: pnpm run build:superdoc
+
+      - name: Lint
+        run: pnpm --filter @superdoc-dev/react lint
+
+      - name: Type check
+        run: pnpm --filter @superdoc-dev/react type-check
+
+      - name: Build
+        run: pnpm --filter @superdoc-dev/react build
+
+      - name: Test
+        run: pnpm --filter @superdoc-dev/react test

.github/workflows/release-react.yml

@@ -0,0 +1,66 @@
+# Auto-releases on push to main (@next channel)
+# For stable (@latest): cherry-pick commits to stable branch, then manually dispatch this workflow
+name: 📦 Release react
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - 'packages/react/**'
+      - 'packages/layout-engine/**'
+      - 'packages/super-editor/**'
+      - 'packages/ai/**'
+      - 'packages/word-layout/**'
+      - 'packages/preset-geometry/**'
+      - '!**/*.md'
+  workflow_dispatch:
+
+permissions:
+  contents: write
+  packages: write
+
+concurrency:
+  group: release-react-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  release:
+    runs-on: ubuntu-24.04
+    steps:
+      - name: Generate token
+        id: generate_token
+        uses: actions/create-github-app-token@v2
+        with:
+          app-id: ${{ secrets.APP_ID }}
+          private-key: ${{ secrets.APP_PRIVATE_KEY }}
+
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+          token: ${{ steps.generate_token.outputs.token }}
+
+      - uses: pnpm/action-setup@v4
+
+      - uses: actions/setup-node@v6
+        with:
+          node-version-file: .nvmrc
+          cache: pnpm
+          registry-url: 'https://registry.npmjs.org'
+
+      - uses: oven-sh/setup-bun@v2
+
+      - name: Install dependencies
+        run: pnpm install
+
+      - name: Build packages
+        run: pnpm run build
+
+      - name: Release
+        env:
+          GITHUB_TOKEN: ${{ steps.generate_token.outputs.token }}
+          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+          LINEAR_TOKEN: ${{ secrets.LINEAR_TOKEN }}
+        working-directory: packages/react
+        run: pnpx semantic-release

CLAUDE.md

@@ -25,6 +25,7 @@ State flows from super-editor → Layout Engine via:
 ```
 packages/
   superdoc/          Main entry point (npm: superdoc)
+  react/             React wrapper (@superdoc-dev/react)
   super-editor/      ProseMirror editor (@superdoc/super-editor)
   layout-engine/     Layout & pagination pipeline
     contracts/       - Shared type definitions
@@ -43,11 +44,12 @@ e2e-tests/           Playwright tests
 
 | Task | Location |
 |------|----------|
+| React integration | `packages/react/src/SuperDocEditor.tsx` |
 | Editing features | `super-editor/src/extensions/` |
 | Presentation mode visuals | `layout-engine/painters/dom/src/renderer.ts` |
 | DOCX import/export | `super-editor/src/core/super-converter/` |
 | Style resolution | `layout-engine/style-engine/` |
-| Main entry point | `superdoc/src/SuperDoc.vue` |
+| Main entry point (Vue) | `superdoc/src/SuperDoc.vue` |
 
 ## When to Modify Which System
 

README.md

@@ -53,7 +53,30 @@ Or install with CDN
 <script type="module" src="https://unpkg.com/superdoc/dist/superdoc.umd.js"></script>
 ```
 
-### Basic usage
+### React
+
+```bash
+npm install @superdoc-dev/react
+```
+
+```tsx
+import { SuperDocEditor } from '@superdoc-dev/react';
+import '@superdoc-dev/react/style.css';
+
+function App() {
+  return (
+    <SuperDocEditor
+      document={file}
+      documentMode="editing"
+      onReady={() => console.log('Ready!')}
+    />
+  );
+}
+```
+
+See the [@superdoc-dev/react README](packages/react/README.md) for full documentation.
+
+### Vanilla JavaScript
 
 ```javascript
 import 'superdoc/style.css';

apps/docs/getting-started/frameworks/nextjs.mdx

@@ -3,124 +3,96 @@ title: Next.js
 keywords: "nextjs docx editor, next word editor, superdoc nextjs, ssr document editor, dynamic import docx"
 ---
 
-SuperDoc works with Next.js using dynamic imports to avoid SSR issues.
+SuperDoc works seamlessly with Next.js. The recommended approach is using `@superdoc-dev/react`, which handles SSR automatically.
 
-## Installation
+## Recommended: Using @superdoc-dev/react
 
-```bash
-npm install @harbour-enterprises/superdoc
-```
-
-## Basic component
-
-```jsx
-// components/DocumentEditor.jsx
-import { useEffect, useRef } from 'react';
-import dynamic from 'next/dynamic';
-
-// Prevent SSR issues
-const DocumentEditor = dynamic(
-  () => Promise.resolve(DocumentEditorComponent),
-  { ssr: false }
-);
-
-function DocumentEditorComponent({ document }) {
-  const containerRef = useRef(null);
-  const superdocRef = useRef(null);
-
-  useEffect(() => {
-    const initEditor = async () => {
-      const { SuperDoc } = await import('@harbour-enterprises/superdoc');
-
-      if (containerRef.current) {
-        superdocRef.current = new SuperDoc({
-          selector: containerRef.current,
-          document
-        });
-      }
-    };
-
-    initEditor();
-
-    return () => {
-      superdocRef.current = null;
-    };
-  }, [document]);
-
-  return <div ref={containerRef} style={{ height: '700px' }} />;
-}
+The React wrapper is the simplest way to integrate SuperDoc with Next.js:
 
-export default DocumentEditor;
+```bash
+npm install @superdoc-dev/react
 ```
 
-## App Router (Next.js 13+)
+### App Router (Next.js 13+)
 
 ```jsx
 // app/editor/page.jsx
 'use client';
 
-import dynamic from 'next/dynamic';
-
-const DocumentEditor = dynamic(
-  () => import('@/components/DocumentEditor'),
-  { 
-    ssr: false,
-    loading: () => <div>Loading editor...</div>
-  }
-);
+import { SuperDocEditor } from '@superdoc-dev/react';
+import '@superdoc-dev/react/style.css';
 
 export default function EditorPage() {
   return (
-    <main>
-      <DocumentEditor document="/sample.docx" />
-    </main>
+    <SuperDocEditor
+      document="/sample.docx"
+      documentMode="editing"
+      onReady={() => console.log('Editor ready!')}
+      style={{ height: '100vh' }}
+    />
   );
 }
 ```
 
-## API route for document handling
-
-```javascript
-// pages/api/documents/[id].js (Pages Router)
-// app/api/documents/[id]/route.js (App Router)
-
-export async function GET(request, { params }) {
-  const docId = params.id;
-
-  // Fetch document from storage
-  const document = await fetchDocumentFromStorage(docId);
-
-  return new Response(document, {
-    headers: {
-      'Content-Type': 'application/vnd.openxmlformats-officedocument.wordprocessingml.document'
-    }
-  });
+### Pages Router
+
+```jsx
+// pages/editor.jsx
+import { SuperDocEditor } from '@superdoc-dev/react';
+import '@superdoc-dev/react/style.css';
+
+export default function EditorPage() {
+  return (
+    <SuperDocEditor
+      document="/sample.docx"
+      documentMode="editing"
+      style={{ height: '100vh' }}
+    />
+  );
 }
 ```
 
-## With authentication
+<Tip>
+The React wrapper is client-only (returns null on server, renders after hydration). For custom loading UI during SSR, use Next.js dynamic imports with a `loading` component.
+</Tip>
 
-```jsx
-// components/SecureEditor.jsx
-import { useSession } from 'next-auth/react';
-import dynamic from 'next/dynamic';
+---
 
-const DocumentEditor = dynamic(() => import('./DocumentEditor'), { ssr: false });
+## CSS Import
 
-export default function SecureEditor() {
-  const { data: session, status } = useSession();
+Import styles in your layout or page:
 
-  if (status === 'loading') return <div>Loading...</div>;
-  if (!session) return <div>Please sign in</div>;
+```jsx
+// app/layout.jsx
+import '@superdoc-dev/react/style.css';
 
+export default function RootLayout({ children }) {
   return (
-    <DocumentEditor 
-      document="/protected-doc.docx"
-      user={{
-        name: session.user.name,
-        email: session.user.email
-      }}
-    />
+    <html>
+      <body>{children}</body>
+    </html>
   );
 }
-```
+```
+
+---
+
+## Next Steps
+
+<CardGroup cols={2}>
+<Card title="React Integration" icon="react" href="/getting-started/frameworks/react">
+  Full React wrapper documentation
+</Card>
+<Card title="Configuration" icon="gear" href="/core/superdoc/configuration">
+  Configuration options
+</Card>
+<Card title="Collaboration" icon="users" href="/modules/collaboration/overview">
+  Real-time collaboration
+</Card>
+<Card title="React Example" icon="github" href="https://github.com/superdoc-dev/superdoc/tree/main/examples/getting-started/react">
+  React + TypeScript example
+</Card>
+<Card title="Next.js Example" icon="github" href="https://github.com/superdoc-dev/superdoc/tree/main/examples/integrations/nextjs-ssr">
+  Next.js SSR integration
+</Card>
+</CardGroup>