dsh-sidebar-superdoc-docx
English | 中文
Open and edit .docx files directly in the DSH web GUI's
better-sidebar editor, powered by SuperDoc — a browser-native DOCX
editor that reads and writes the real OOXML (no server-side document service needed).
Dependency: this plugin registers its file viewer with
dsh-better-sidebar (>= 0.13.0) — a mandatory peer
dependency. Without it, the viewer never appears. Install it first (or together with this plugin).
⚠️ License notice: this plugin's own code is MIT, but it integrates AGPL-3.0 superdoc and the
proprietary-licensed @superdoc/docx-engine at runtime — installing it means accepting those terms. See
License below and THIRD-PARTY-NOTICES.md.
Features
- Browser-native DOCX editing — view and edit
.docx in the sidebar with comments and tracked changes; three
open modes selectable in the settings page: editing / suggesting / viewing.
- Save back to disk — the
Save button exports the edited document and atomically overwrites the opened
file through a dedicated route (tmp + rename, never a half-written state); unsaved edits show a ● dot.
- Follows outside edits — a 3s disk poll: a clean editor auto-swaps to the new version in place
(
replaceFile); a dirty editor only shows a banner with a manual Reload — your edits are never silently
dropped.
- Fully self-hosted & offline-capable — the SuperDoc editor build and the DOCX engine (web workers included)
are served same-origin from this package's
node_modules: no CDN traffic, no third-party document service,
telemetry off by default. Fully offline after pnpm install.
- Download fallback — every surface (including all error states) keeps a plain download link.
- Sidebar-adaptive — the toolbar folds into an overflow menu as the pane narrows; pages fit-to-pane zoom;
readable in light and dark themes.
Use cases
- Human–AI collaboration on one Word file: the AI agent edits a
.docx in the session; you see the new
version in the sidebar within seconds, polish it by hand, save — and the agent's next turn works from the
latest version. A two-way loop without interruptions.
- Intranet / offline / compliance environments: deployments that must not reach CDNs such as jsdelivr or
SaaS document services; every asset is self-hosted same-origin.
- No document server wanted: unlike OnlyOffice / Collabora, which need a separate Document Server, this
plugin has zero service dependencies — install and go.
- Document review workflows: open in
suggesting mode; comments and suggestions land as tracked changes.
- Quick preview: replaces the built-in code/download viewers — click a
.docx in the file tree and see the
paginated document, with a download link one click away.
Installation
Prerequisites
- Node.js
>= 20;
- the DSH web GUI and its
web profile;
dsh-better-sidebar >= 0.13.0 installed in the same profile (see the dependency note above).
From npm (recommended)
The package is published on npmjs as dsh-sidebar-superdoc-docx:
dsh plugin --profile web add dsh-better-sidebar dsh-sidebar-superdoc-docx
Or by hand: edit the profile's package.json (e.g. ~/.dsh/profiles/web/package.json), add the two
npm dependencies and the bundle entries, then run pnpm install in the profile directory:
{
"dependencies": {
"dsh-better-sidebar": ">=0.13.0",
"dsh-sidebar-superdoc-docx": "^0.1.0"
},
"dsh": { "profile": { "bundles": ["…", "dsh-better-sidebar", "dsh-sidebar-superdoc-docx"] } }
}
Finally restart dsh web (the host half must reload) and hard-refresh the browser (Ctrl/Cmd+Shift+R).
From GitHub (source / development)
dsh plugin --profile web add github:chendefine/dsh-sidebar-superdoc-docx
For local development, clone, build, and link:
git clone https://github.com/chendefine/dsh-sidebar-superdoc-docx
cd dsh-sidebar-superdoc-docx
pnpm install
pnpm build # → lib/index.js + lib/client.js + lib/types
then, in the profile's package.json, point the dependency at the clone and run pnpm install
in the profile directory:
{
"dependencies": {
"dsh-sidebar-superdoc-docx": "link:/absolute/path/to/dsh-sidebar-superdoc-docx"
}
}
Plugin config (cordis.patch.yml of the profile)
- id: dsh-sidebar-superdoc-docx
config:
fileLimitMb: 100 # save-route size cap in MB, default 100
allowOutsideWorkspace: false # allow saving files resolved outside the session cwd, default false
Usage
Opening a document
Click any .docx in the sidebar file tree — it opens in the DOCX (SuperDoc) viewer instead of the built-in
code/download viewers.
Switching the open mode
Under Settings → Side cards → File preview → DOCX (SuperDoc), the gear exposes the "open mode" select:
editing / suggesting / viewing. The choice persists in pluginSettings['superdoc:docx'].mode and takes effect
immediately (the editor remounts in the new mode); viewing also hides the save button.
Editing & saving
- The top toolbar is SuperDoc's native one (bold, lists, comments, …) and folds automatically as the pane narrows;
- after edits, the header shows
● Unsaved changes; click Save to export and atomically write back to the
opened path;
- state machine: Saving… → Saved / Save failed (failures carry a reason and can be retried); edits made while a
save is in flight keep the unsaved hint so you can re-save.
Following outside edits (e.g. an AI agent edited the file)
- clean editor: the 3s poll detects the disk change → re-fetches and swaps in place via
replaceFile,
re-fitting the zoom;
- dirty editor: only a "File changed on disk" banner appears — you decide whether to
Reload (reloading
discards the current unsaved edits).
Coexistence with other viewers
| Viewer | id | priority |
|---|
| built-in code viewer | code | -100 |
| built-in download viewer | binary-download | -50 |
| office preview plugin | docx | 0 |
| OnlyOffice plugin | onlyoffice:docx | 10 |
| this plugin | superdoc:docx | 10 |
Ties (e.g. with OnlyOffice) break by registration order. Every viewer can be toggled individually under
Settings → Side cards → File preview without affecting the others.
Architecture
Two halves
browser (client half, tiny CJS bundle via window.__ModuleLoader__)
└─ ctx.betterSidebar.registerFileViewer('superdoc:docx', exts:['docx'], priority:10, fetchStrategy:'mediaUrl')
└─ SuperDocView: <script src="/sidebar/superdoc/assets/superdoc.min.js"> (global `SuperDoc`)
reads: fetch(/sidebar/file?sessionId=&path=) → Blob → new SuperDoc({ document: blob, contained: true })
saves: superdoc.export({triggerDownload:false}) → Blob → PUT /sidebar/superdoc/save?sessionId=&path=
node (host half, 4 fenced routes)
├─ GET /sidebar/superdoc/info versions / health / cache-bust seed
├─ GET /sidebar/superdoc/assets/<file> superdoc/dist-cdn (closed whitelist)
├─ GET /sidebar/superdoc/engine/dist-cdn/<path> @superdoc/docx-engine/dist-cdn mirror (engine + workers)
└─ PUT /sidebar/superdoc/save raw DOCX bytes → atomic write inside the session cwd
- the client half does exactly three things: register the viewer, fetch the file bytes through better-sidebar's
fenced media route, and mount the SuperDoc instance into the sidebar pane;
- the host half runs no document logic — it only serves assets same-origin and fenced saves;
- vendored versions:
superdoc@2.10.0 + @superdoc/docx-engine@0.9.0 (per package.json; the info route
reports the installed versions and doubles as the cache-bust seed).
Why the engine mirror exists
Before the script loads, the client sets globalThis.SUPERDOC_ENGINE_CDN_BASE_URL = '/sidebar/superdoc/engine',
pointing SuperDoc's engine resolver at this plugin's route. The engine then dynamic-imports
…/dist-cdn/docx-engine.es.js and resolves its web workers relative to that same-origin URL — browsers
refuse cross-origin worker creation, and otherwise jsdelivr would become a runtime dependency. That is the entire
reason the host half mirrors the dist-cdn tree.
Security boundaries
- Trust fence (
src/trust-fence.ts, behaviorally identical to better-sidebar's): the Host header must be
loopback or a trusted authority from webRuntime.trustedHosts; sec-fetch-site: cross-site and mismatched
Origins are refused — a DNS-rebinding / cross-site defense, not authentication.
- Workspace fence (
src/paths.ts + the save route): absolute paths only; isWithin compares path segments
(/a/bc is not within /a/b); the parent directory is realpath-checked to close symlink escapes; .docx
only; bodies above fileLimitMb get a 413; writes go through tmp + rename atomic replacement.
- Asset whitelisting (
src/assets.ts): the superdoc build exposes a closed whitelist of 3 files; engine
subpaths pass a shape check, reject ./.. segments, and must realpath inside dist-cdn as regular files.
- No leakage: telemetry off by default (
telemetry: { enabled: false }); the plugin keeps no state on disk.
Development details & conventions
Directory layout
src/
index.ts host half: build & register the 4 routes (buildRoutes is pure, test-friendly)
assets.ts node_modules asset discovery / whitelists / realpath containment / content types
config.ts config resolution (fileLimitMb, allowOutsideWorkspace; plain TS, zero deps)
paths.ts absolute-path requirement + segment-aware containment + symlink-safe parent realpath
trust-fence.ts browser trust fence (copied, not imported — plugins must not depend on upstream internals)
wire.ts {ok,...} / {ok:false,error:{code,message}} JSON shape + size-capped raw-body reader
client/
index.ts client half: register the superdoc:docx viewer + attach dictionaries
SuperDocView.tsx the editor component (mount / save state machine / disk poll / fit-to-pane zoom)
loader.ts runtime loader (script/stylesheet singletons, engine base URL, contained layout CSS)
settings.ts open-mode read (validated, falls back to editing)
urls.ts URL builders for /sidebar/file and the save route (better-sidebar request contract)
i18n.ts / locales.ts / icons.tsx zh/en dictionaries, registration, icons
tests/ vitest: routes / save-flow / viewers / trust-fence / locales
Build artifacts
- host:
lib/index.js, ESM (es2023), zero runtime dependencies;
- client:
lib/client.js — a CJS bundle registered via window.__ModuleLoader__.load({ id, factory }), the
official external client-plugin delivery format (same shape as dsh-sidebar-onlyoffice and
dsh-web-search-aggregation);
- the SuperDoc editor itself is not bundled: the host routes inject it at runtime as a classic
<script>
(structurally identical to how onlyoffice loads its api.js).
Client purity gate
tsdown.config.ts ships a rolldown plugin that fails the build when the client bundle imports any Node builtin
or value-imports @deepseek-ai/*; React / react-dom / cordis stay external and come from the host's module
table. The browser half must be self-contained.
Code conventions
- No imports of monorepo-internal types: both halves declare structural context faces (
RouteContext,
ClientContextFace) — external plugins must not reach into the monorepo's Context augmentation graph;
- browser JSON is always
{ok:...} / {ok:false,error:{code,message}} (aligned with better-sidebar's wire
format); error codes: forbidden / method-error / bad-request / not-found / fs-error / internal;
- the viewer id is namespaced (
superdoc:docx) to avoid clashes with the builtins and onlyoffice:docx;
priority 10 beats the builtins; fetchStrategy: 'mediaUrl';
- the zh/en dictionaries must carry exactly the same key set (enforced by the locales test) under the plugin's
single
dshSidebarSuperdoc namespace;
- every page-level injection is idempotent (stylesheet, layout CSS, editor script are singletons — remount-safe);
- the save route is the only fs write surface; better-sidebar's own
fs.write is UTF-8-text-only, so binary
exports must go through it.
Tests
pnpm test (vitest run) covers:
| File | Coverage |
|---|
routes.test.ts | the 4 routes: whitelist hits / traversal & symlink refusals / workspace fence on & off / 413 / 405 / 403 |
save-flow.test.ts | save state machine: hint clears after a successful save, in-flight edits stay unsaved, header buttons position-stable |
viewers.test.ts | viewer contract: id / exts / priority / fetchStrategy / settings row; no id clash with existing viewers |
trust-fence.test.ts | loopback & trusted authorities pass; unknown hosts / cross-site markers / mismatched origins refused |
locales.test.ts | zh/en key parity, non-empty values, unique namespace |
Common commands
pnpm typecheck # tsc --noEmit
pnpm test # vitest run
pnpm build # host ESM + client ModuleLoader bundle (purity gate enforced)
Known limitations
- Only
.docx (SuperDoc does not open legacy .doc).
- Closing the tab with unsaved edits cannot be intercepted — watch the
● unsaved dot.
- If better-sidebar's
workspaceFence is disabled, files outside the workspace can be opened through the media
route, but saving them still requires allowOutsideWorkspace: true here.
- Fonts: SuperDoc core ships no fonts; documents render with system fonts unless you additionally integrate
@superdoc-dev/fonts (not wired up here).
License
This plugin's code is MIT. It integrates (unmodified, installed by pnpm install and served verbatim by its
routes) two SuperDoc components:
| Package | License | Note |
|---|
superdoc | AGPL-3.0 | unmodified npm artifact; network-service use triggers AGPL source-offer duties |
@superdoc/docx-engine | Proprietary (DOCX Engine Proprietary License) | without a commercial agreement, use is limited to SuperDoc-dependent, AGPL-permitted purposes (evaluation/development/testing); commercial use needs a SuperDoc license |
See THIRD-PARTY-NOTICES.md.
Credits
- SuperDoc by Harbour Enterprises — the editor itself.
- dsh-sidebar-onlyoffice — the plugin shape (runtime
script injection, trust fence, host routes) this package follows.
