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

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

Enable docs contributors to preview interactive widgets with local source changes. `pnpm dev:docs` starts the Vite dev server, UMD watcher, and Mintlify in parallel.

  - Refactor SuperDocEditor widget to load from local dev server on localhost
  - Add serve-dist-for-docs Vite plugin to serve UMD bundle over CORS
  - Add watch:umd script with debounced rebuilds (300ms)
  - Document the workflow in apps/docs/README.md

* fix: fallback to unpkg bundle when the superdoc dev server is not running

* fix: conditionally apply watch buildDelay only for watch mode

Set build.watch.buildDelay only when --watch flag is passed via CLI.
This prevents 'pnpm build' from hanging in watch mode while still
allowing buildDelay to debounce rebuilds in watch:umd and dev:docs.

* fix(docs): remove void operator and add proper error handling in superdoc-editor snippet

Move error handling into the async boot() function to properly catch and
log initialization errors instead of discarding the Promise with void.

* fix(docs): add defensive check after script query in superdoc-editor snippet

Check if SuperDocLibrary loaded between outer check and DOM query to handle
edge case where library finishes loading during synchronous code execution.

* fix(docs): add error rejection handling to script load in superdoc-editor snippet

Author: lucbic

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,95 @@ 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) {
+      if (window.SuperDocLibrary) return Promise.resolve();
+
+      return new Promise((resolve, reject) => {
+        existingScript.addEventListener('load', resolve, { once: true });
+        existingScript.addEventListener('error', reject, { 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 () => {
+      try {
+        const baseUrl = await getBaseUrl();
+        ensureStyle(baseUrl);
+        await loadSuperDocLibrary(baseUrl);
+        if (!cancelled) initEditor();
+      } catch (error) {
+        console.error('Failed to boot SuperDoc:', error);
+      }
     };
-    document.body.appendChild(script);
 
-    return () => editorRef.current?.destroy?.();
+    boot();
+
+    return () => {
+      cancelled = true;
+      editorRef.current?.destroy?.();
+      editorRef.current = null;
+    };
   }, []);
 
   const exportDocx = () => {

package.json

@@ -32,7 +32,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",
@@ -86,6 +86,7 @@
   "devDependencies": {
     "@clack/prompts": "^1.0.1",
     "@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",
@@ -99,9 +100,9 @@
     "@superdoc/common": "workspace:*",
     "@superdoc-dev/superdoc-yjs-collaboration": "workspace:*",
     "@superdoc/super-editor": "workspace:*",
-    "concurrently": "catalog:",
     "@vitejs/plugin-vue": "catalog:",
     "@vue/test-utils": "catalog:",
+    "concurrently": "catalog:",
     "jszip": "catalog:",
     "nodemon": "catalog:",
     "pdfjs-dist": "catalog:",
@@ -110,6 +111,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

@@ -19,6 +19,7 @@ export default defineConfig(({ command }) => {
       conditions: ['source'],
     },
     build: {
+      ...(process.argv.includes('--watch') && { watch: { buildDelay: 300 } }),
       emptyOutDir: false,
       target: 'es2022',
       cssCodeSplit: false,

pnpm-lock.yaml

@@ -98,6 +98,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