docs(dev): add dev:docs workflow for local SuperDoc development

apps/docs/README.md

@@ -37,10 +37,26 @@ pnpm dev
 
 ## Development
 
+### Developing with local SuperDoc changes
+
+To preview docs with your local SuperDoc source (instead of the published npm version), run from the **repo root**:
+
+```bash
+pnpm dev:docs
+```
+
+This starts three processes:
+
+- **Vite dev server** (port 9094) — serves the built UMD bundle at `/dist`
+- **UMD watcher** — rebuilds `dist/superdoc.umd.js` automatically when source files change
+- **Mintlify** (port 3001) — the docs dev server
+
+The `<SuperDocEditor>` widget detects `localhost` and loads SuperDoc from the local Vite server instead of unpkg. After saving a source file, the UMD watcher rebuilds automatically — refresh the docs page to see the changes.
+
 ### Available Scripts
 
-- `pnpm dev` - Start Mintlify development server
-- `pnpm build` - Build documentation for production
+- `pnpm dev` - Start Mintlify development server (uses unpkg, no local changes)
+- `pnpm dev:docs` - Start full local dev environment (**run from repo root**)
 - `pnpm sync:api` - Sync API documentation from OpenAPI spec
 - `pnpm sync:sdk` - Sync SDK documentation from TypeDoc
 - `pnpm sync:all` - Sync both API and SDK documentation

apps/docs/snippets/components/superdoc-editor.jsx

@@ -9,33 +9,88 @@ export const SuperDocEditor = ({
   const [ready, setReady] = useState(false);
   const editorRef = useRef(null);
   const containerIdRef = useRef(`editor-${Math.random().toString(36).substr(2, 9)}`);
+  const DEV_DIST_URL = 'http://localhost:9094/dist';
+  const UNPKG_DIST_URL = 'https://unpkg.com/superdoc@latest/dist';
+
+  const getBaseUrl = async () => {
+    const isDev = typeof window !== 'undefined' && window.location.hostname === 'localhost';
+
+    if (isDev) {
+      try {
+        const res = await fetch(`${DEV_DIST_URL}/superdoc.umd.js`, { method: 'HEAD' });
+        if (res.ok) return DEV_DIST_URL;
+      } catch {}
+    }
+
+    return UNPKG_DIST_URL;
+  };
+
+  const ensureStyle = (baseUrl) => {
+    const styleHref = `${baseUrl}/style.css`;
+    if (document.querySelector(`link[href="${styleHref}"]`)) return;
 
-  useEffect(() => {
     const link = document.createElement('link');
     link.rel = 'stylesheet';
-    link.href = 'https://unpkg.com/superdoc@latest/dist/style.css';
+    link.href = styleHref;
     document.head.appendChild(link);
+  };
 
-    const script = document.createElement('script');
-    script.src = 'https://unpkg.com/superdoc@latest/dist/superdoc.umd.js';
-    script.onload = () => {
-      setTimeout(() => {
-        if (window.SuperDocLibrary) {
-          editorRef.current = new window.SuperDocLibrary.SuperDoc({
-            selector: `#${containerIdRef.current}`,
-            html,
-            rulers: true,
-            onReady: () => {
-              setReady(true);
-              if (onReady) onReady(editorRef.current);
-            },
-          });
-        }
-      }, 100);
+  const loadSuperDocLibrary = (baseUrl) => {
+    if (window.SuperDocLibrary) return Promise.resolve();
+
+    const scriptSrc = `${baseUrl}/superdoc.umd.js`;
+    const existingScript = document.querySelector(`script[src="${scriptSrc}"]`);
+
+    if (existingScript) {
+      return new Promise((resolve) => {
+        existingScript.addEventListener('load', resolve, { once: true });
+      });
+    }
+
+    return new Promise((resolve, reject) => {
+      const script = document.createElement('script');
+      script.src = scriptSrc;
+      script.onload = resolve;
+      script.onerror = reject;
+      document.body.appendChild(script);
+    });
+  };
+
+  const initEditor = () => {
+    setTimeout(() => {
+      if (!window.SuperDocLibrary) return;
+      if (!document.getElementById(containerIdRef.current)) return;
+      if (editorRef.current) return;
+
+      editorRef.current = new window.SuperDocLibrary.SuperDoc({
+        selector: `#${containerIdRef.current}`,
+        html,
+        rulers: true,
+        onReady: () => {
+          setReady(true);
+          if (onReady) onReady(editorRef.current);
+        },
+      });
+    }, 100);
+  };
+
+  useEffect(() => {
+    let cancelled = false;
+
+    const boot = async () => {
+      const baseUrl = await getBaseUrl();
+      ensureStyle(baseUrl);
+      await loadSuperDocLibrary(baseUrl);
+      if (!cancelled) initEditor();
     };
-    document.body.appendChild(script);
 
-    return () => editorRef.current?.destroy?.();
+    void boot();
+
+    return () => {
+      cancelled = true;
+      editorRef.current?.destroy?.();
+      editorRef.current = null;
+    };
   }, []);
 
   const exportDocx = () => {

package.json

@@ -29,7 +29,7 @@
     "dev:super-editor": "pnpm --prefix packages/super-editor run dev",
     "dev:collab": "pnpm --prefix packages/superdoc run dev:collab",
     "word-benchmark-sidecar": "pnpm --prefix packages/superdoc run word-benchmark-sidecar",
-    "dev:docs": "pnpm --prefix apps/docs run dev",
+    "dev:docs": "concurrently -k -n VITE,UMD,DOCS -c cyan,yellow,green \"pnpm --prefix packages/superdoc run dev\" \"pnpm --prefix packages/superdoc run watch:umd\" \"pnpm --prefix apps/docs run dev\"",
     "build:superdoc": "pnpm --prefix packages/superdoc run build",
     "build:super-editor": "pnpm --prefix packages/super-editor run build",
     "build": "pnpm run build:superdoc && pnpm run type-check",
@@ -80,6 +80,7 @@
   },
   "devDependencies": {
     "@commitlint/cli": "catalog:",
+    "concurrently": "catalog:",
     "@commitlint/config-conventional": "catalog:",
     "@eslint/js": "catalog:",
     "@semantic-release/changelog": "catalog:",

packages/superdoc/package.json

@@ -69,6 +69,7 @@
     "build:es": "vite build && node ./scripts/ensure-types.cjs",
     "watch:es": "vite build --watch",
     "build:umd": "vite build --config vite.config.umd.js",
+    "watch:umd": "vite build --watch --config vite.config.umd.js",
     "clean": "rm -rf dist",
     "pack:local": "pnpm run pack",
     "pack": "pnpm run build:es && pnpm pack && mv $(ls superdoc-*.tgz) ./superdoc.tgz",
@@ -98,9 +99,9 @@
     "@hocuspocus/server": "catalog:",
     "@superdoc/common": "workspace:*",
     "@superdoc/super-editor": "workspace:*",
-    "concurrently": "catalog:",
     "@vitejs/plugin-vue": "catalog:",
     "@vue/test-utils": "catalog:",
+    "concurrently": "catalog:",
     "jszip": "catalog:",
     "nodemon": "catalog:",
     "pdfjs-dist": "catalog:",
@@ -109,6 +110,7 @@
     "prosemirror-model": "catalog:",
     "prosemirror-state": "catalog:",
     "rollup-plugin-visualizer": "catalog:",
+    "sirv": "catalog:",
     "typescript": "catalog:",
     "vite": "catalog:",
     "vite-plugin-dts": "catalog:",

packages/superdoc/vite.config.js

@@ -1,6 +1,7 @@
 import path from 'path';
 import copy from 'rollup-plugin-copy'
 import dts from 'vite-plugin-dts'
+import sirv from 'sirv';
 import { defineConfig } from 'vite'
 import { configDefaults } from 'vitest/config'
 import { createRequire } from 'node:module';
@@ -89,6 +90,21 @@ export default defineConfig(({ mode, command }) => {
       hook: 'writeBundle'
     }),
     // visualizer(visualizerConfig)
+    {
+      // Serve dist/ as static files so the docs dev server can load the local UMD build - Development only.
+      name: 'serve-dist-for-docs',
+      configureServer(server) {
+        server.middlewares.use(
+          '/dist',
+          sirv(path.resolve(__dirname, 'dist'), {
+            dev: true,
+            setHeaders(res) {
+              res.setHeader('Access-Control-Allow-Origin', '*');
+            },
+          }),
+        );
+      },
+    },
   ].filter(Boolean);
   if (mode !== 'test') plugins.push(nodePolyfills());
   const isDev = command === 'serve';

packages/superdoc/vite.config.umd.js

@@ -20,6 +20,9 @@ export default defineConfig(({ command }) => {
     },
     build: {
       emptyOutDir: false,
+      watch: {
+        buildDelay: 300,
+      },
       target: 'es2022',
       cssCodeSplit: false,
       lib: {

pnpm-workspace.yaml

@@ -93,6 +93,7 @@ catalog:
   semantic-release: ^24.2.7
   semantic-release-commit-filter: ^1.0.2
   semantic-release-linear-app: ^0.7.1
+  sirv: ^3.0.2
   tippy.js: ^6.3.7
   tsup: ^8.5.1
   tsx: ^4.20.6