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

[tupizz]

Summary

Adds @superdoc-dev/react - a first-party React wrapper for SuperDoc with proper lifecycle management, SSR safety, and React Strict Mode compatibility.

Closes SD-1716

Key Design Decisions

Decision	Choice
Type system	Types extracted from superdoc (no duplication)
Ref API	Single getInstance() method
Style import	@superdoc-dev/react/style.css
React version	16.8+ (uses useRef for ID generation)
SSR behavior	Client-only (renders renderLoading if provided, otherwise null)
documentMode	Prop changes handled without rebuild

Package Structure

packages/react/
├── src/
│   ├── index.ts              # Exports
│   ├── SuperDocEditor.tsx    # Main component
│   ├── SuperDocEditor.test.tsx
│   ├── types.ts              # Types extracted from superdoc
│   └── utils.ts              # ID generation (internal)
├── style.css                 # Re-exports superdoc/style.css
├── package.json
├── tsconfig.json
├── vite.config.ts
└── vitest.config.ts

Usage

import { SuperDocEditor } from '@superdoc-dev/react';
import '@superdoc-dev/react/style.css';

function App() {
  const [mode, setMode] = useState<DocumentMode>('editing');
  const editorRef = useRef<SuperDocRef>(null);
  
  return (
    <>
      <button onClick={() => setMode('viewing')}>View</button>
      <SuperDocEditor
        ref={editorRef}
        document={file}
        documentMode={mode}
        onReady={({ superdoc }) => console.log('Ready!')}
      />
    </>
  );
}

// Access instance via ref for methods
await editorRef.current?.getInstance()?.export({ triggerDownload: true });

Props

All props from SuperDocConfig are supported, plus React-specific props:

Prop	Type	Default	Description
document	File | Blob | string | object	-	Document to load
documentMode	'editing' | 'viewing' | 'suggesting'	'editing'	Editing mode
role	'editor' | 'viewer' | 'suggester'	'editor'	User role
id	string	auto-generated	Custom container ID
user	{ name, email?, image? }	-	Current user
users	Array<{ name, email, image? }>	-	All users
modules	object	-	Modules config
hideToolbar	boolean	false	Hide the toolbar
renderLoading	() => ReactNode	-	Loading UI (shown during SSR and init)
className	string	-	Wrapper CSS class
style	CSSProperties	-	Wrapper inline styles

Props That Trigger Rebuild

Prop	Reason
document	New document to load
user	User identity changed
users	Users list changed
modules	Module configuration changed
role	Permission level changed
hideToolbar	Toolbar visibility changed

Other props like documentMode and callbacks are handled efficiently without rebuild.

Ref API

interface SuperDocRef {
  getInstance(): SuperDocInstance | null;
}

Examples

Example	Description
examples/getting-started/react	React + TypeScript example with full type safety
examples/integrations/nextjs-ssr	Next.js App Router with SSR support

Run examples from repo root:

pnpm -C examples/getting-started/react dev
pnpm -C examples/integrations/nextjs-ssr dev

Documentation Updated

• apps/docs/getting-started/frameworks/react.mdx - Full React integration guide
• apps/docs/getting-started/frameworks/nextjs.mdx - Next.js integration guide
• packages/react/README.md - Package README
• packages/react/CLAUDE.md - Implementation details for AI assistants

Test Plan

• pnpm --filter @superdoc-dev/react build succeeds
• pnpm --filter @superdoc-dev/react test passes (14 tests)
• Example apps run and load documents
• Types correctly extracted from superdoc
• Ref API works as expected
• Docs consistent with implementation

[linear]

SD-1716 Feat: React wrapper for SuperDoc [Tadeu]

[caio-pizzol]

good start!

the whole point of the React package is to provide the best DX as possible to (react) developers starting with SuperDoc - so let's make sure we nail the basics and keep it simple.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: cba407d124

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[superdoc-bot]

🎉 This PR is included in @superdoc-dev/react v1.0.0-canary.5

The release is available on GitHub release

[superdoc-bot]

🎉 This PR is included in @superdoc-dev/react v1.0.0-canary.6

The release is available on GitHub release

[superdoc-bot]

🎉 This PR is included in @superdoc-dev/react v1.0.0-canary.7

The release is available on GitHub release

[Copilot]

Pull request overview

Copilot reviewed 55 out of 68 changed files in this pull request and generated 5 comments.

Files not reviewed (1)

• pnpm-lock.yaml: Language not supported

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

effectDocumentMode is taken from initialDocumentModeRef.current, but that ref is only updated inside this rebuild effect (which does not depend on documentMode). If documentMode changes without a rebuild and later a rebuild is triggered (e.g., document changes), the new SuperDoc instance can be initialized with a stale mode. Use the current documentMode value for this effect run (or update the ref in a separate useEffect that depends on documentMode).

[Copilot]

The wrapper always injects its own toolbar selector when hideToolbar is false, which will override a user-provided toolbar prop even though SuperDocConfig supports custom toolbars. Either (1) only set toolbar when the caller did not provide one, or (2) omit toolbar from the exposed props / document that toolbar is managed internally.

[Copilot]

The @version 1.0.0 tag in the package documentation header doesn’t match package.json version (0.1.0). This can confuse users and tooling that surfaces TSDoc headers; update the tag to match the package version or remove it.

[Copilot]

This example pins react/react-dom to 19.2.3 while the workspace catalog was bumped to 19.2.4, which can lead to multiple React copies in the monorepo install and confusing hook/type issues. Prefer aligning to the workspace version (e.g., catalog: or the same 19.2.4 range) unless there’s a specific reason to stay on 19.2.3.

Suggested change

	"react": "19.2.3",
	"react-dom": "19.2.3"
	"react": "workspace:*",
	"react-dom": "workspace:*"

[Copilot]

In the TypeScript example, handleReady uses { superdoc: any }, which undermines the “full TypeScript support” claim. Consider using the exported SuperDocReadyEvent (or SuperDocInstance) type for the callback parameter instead of any.