▦
Embed the surface
Give your SaaS, internal tool or AI app a real editable workbook or document instead of building one from scratch.
UNIVERoffice sdk
Repository deep dive
Build your own office layer.
Univer is an open-source SDK for embedding spreadsheet, document and presentation experiences inside products you already own.
Univer · dream-num•Inspected 26 Sep 2026
UNIVER
runtime
runtime
Sheets
Docs
Slides
Headless
AI workflows
01 · Plain-English summary
Univer is the office engine you can put inside your own product.
⌘
Compose the runtime
Pick a quick preset or assemble plugins yourself. Add, remove, replace or lazy-load capabilities as your product grows.
◌
Keep humans in the loop
Agents can inspect and edit structured Office content, while people review the result in a familiar interactive surface.
The useful mental model: Univer isn’t “a spreadsheet viewer”. It’s a framework for building your own productivity surface, with browser UI and Node.js headless processing sharing the same architecture.
The product opportunity
Move from documents as destinations to documents as product primitives.
Your product context
The workflow, data, permissions and AI experience you already own.
MetricsControlsAgent actionsReviewApprovalsAudit trail
↔
Univer runtime office surface
Structured content, formulas, commands, rendering and Facade APIs.
SheetsDocsSlidesHeadlessPluginsLocales
Why teams use it
Four benefits. Four concrete product shapes.
01 · Embed
AI-native workspaces
An agent creates a decision dashboard, report or mini-app inside a workspace. Web controls and metrics can bind to cells and update collaboratively.
Example: Univer Workspace or an internal planning cockpit.
02 · Automate
Headless document operations
Run workbook or document logic on the server for generation, inspection, formula calculation or workflow automation without rendering a UI.
Example: an agent prepares a budget pack overnight.
03 · Extend
Focused vertical tools
Compose the editor around the job: add domain menus, validation, approval steps, custom commands or embedded components.
Example: a recipe costing, supply planning or product-quality tool.
04 · Reuse
One model across surfaces
Keep structured content and higher-level APIs consistent across browser and Node.js paths, rather than maintaining separate business logic.
Example: generate in Node, review in the browser.
02 · Deep dive
Under the hood: a runtime you can compose.
Most of the leverage comes from the seams: plugins, shared models, rendering and a Facade API that make the same core useful to an app, an agent and a server process.
Architecture
Four layers, one working surface.
Product surface
Sheets · Docs · Slides · Bases
The experiences your user sees or your agent targets. Sheets are the most mature surface today; Docs and Slides continue to evolve.
The experiences your user sees or your agent targets. Sheets are the most mature surface today; Docs and Slides continue to evolve.
UI & render
Canvas rendering · React UI · interactions · themes
A canvas-based rendering engine handles layout, primitives, scrolling, zooming and interaction layers.
A canvas-based rendering engine handles layout, primitives, scrolling, zooming and interaction layers.
Core runtime
Data models · commands · mutations · dependency injection
Shared business logic lives below the UI, making it possible to run product behaviours in more than one environment.
Shared business logic lives below the UI, making it possible to run product behaviours in more than one environment.
Integration
Facade API · plugins · presets · locales
Use a high-level API for app code, or go lower-level when building extensions and custom runtimes.
Use a high-level API for app code, or go lower-level when building extensions and custom runtimes.
Isomorphic by design
Build in the browser. Process in Node. Share the logic.
Shared Univer core
models · commands · Facade
models · commands · Facade
Browser UIReact, Canvas, menus, shortcuts
Node.jsheadless generation, inspection, automation
Your apppermissions, storage, auth, AI
Agent loopread → act → verify → review
client path
server path
Design implication: keep feature logic, models, commands and mutations free of browser-only state. Put menus, shortcuts and React components in a separate UI plugin.
Composition model
Start with a preset. Graduate to plugins when the product gets opinionated.
✦
Preset mode
Curated plugin collections for a fast working Sheets, Docs or Node setup. Good for prototypes, internal tools and a first product slice.
Choose it when:
You want a short integration path and sensible defaults.
You want a short integration path and sensible defaults.
⊞
Plugin mode
Manually register packages, styles, locales, Facade APIs and configuration. Good for smaller bundles, lazy loading or custom runtime composition.
Choose it when:
You need strict control over the runtime boundary.
You need strict control over the runtime boundary.
The extension seam
Put the business action in the model. Let the UI be one client.
1
ModelStructured workbook or document state, with the data contracts your feature needs.
2
Command / mutationOne explicit action that can be triggered by a user, agent or server workflow.
3
ServiceDependency-injected capability for storage, calculation, events or other runtime work.
4
Facade APIA higher-level interface that keeps app code away from internal implementation details.
conceptual plugin shape
export class QualityGatePlugin { onStarting(injector) { injector.add(IQualityGateService, { validate: (workbook) => { // shared logic: browser + Node return checkRanges(workbook) } }) } } // UI plugin owns menus and shortcuts export class QualityGateUIPlugin { onStarting() { /* React / Canvas UI */ } }
AI workflow
Agents get a structured workspace, not just a text box.
01
Inspect
Read workbook or document structure through APIs instead of guessing from a screenshot.
02
Act
Write values, formulas or document content through explicit, reviewable operations.
03
Verify
Check content, render output, screenshots and layout diagnostics before delivery.
04
Review
Keep a human in the loop with drafts, shared revisions or isolated worktrees where needed.
Product insight: the winning AI experience isn’t “AI inside a spreadsheet”. It’s an agent that can make structured changes, explain them, and hand a polished artefact back to a person.
Availability of live collaboration, shared revisions and worktree workflows depends on the relevant Web SDK, collaboration capabilities and licensing.
Scope check
Know what the open-source repo gives you — and where Pro begins.
Surface
Open source
Pro / commercial
Foundation
Core SDK, plugin system, rendering, formula engine, Facade API, themes, i18n.
Pro presets and enterprise deployment packages.
Sheets
Editing, formulas, formatting, filter/sort, validation, comments, notes, tables and drawing integration.
Collaboration, import/export, print, charts, pivots, connectors and enhanced formula features.
Docs
Document model and editor UI, lists, links, comments and drawing integration.
Collaboration, import/export, print, enhanced layout and remote resources.
Slides
Presentation data model and UI packages under active development.
Pro slide model/UI, import/export, charts, tables and shared shape editing.
Runtime
Browser apps, Node headless usage, Web Worker/RPC patterns and automation primitives.
Collaboration server, SSR, server-side calculation and replay tooling.
03 · Build it
A practical path from zero to a product-shaped prototype.
Start narrow: one surface, one workflow, one validation loop. Add collaboration and deeper customisation only when the product earns it.
Step-by-step guide
The shortest path to a working Sheets surface.
Choose the boundary browser / Node
Decide whether the first slice is interactive, headless or both. Keep the domain workflow outside the editor core.
Start with a preset fast path
Use @univerjs/presets plus @univerjs/preset-sheets-core for a minimal browser setup.
Register the container UI
Give Univer a full-height element, create a workbook, then mount your app shell around it.
Prove one workflow vertical slice
For example: import data → calculate → flag exceptions → ask for review → export or hand off.
preset mode · TypeScript
import { UniverSheetsCorePreset } from '@univerjs/preset-sheets-core' import presetEnUS from '@univerjs/preset-sheets-core/locales/en-US' import { createUniver, LocaleType, mergeLocales } from '@univerjs/presets' import '@univerjs/preset-sheets-core/lib/index.css' const { univerAPI } = createUniver({ locale: LocaleType.EN_US, locales: { [LocaleType.EN_US]: mergeLocales(presetEnUS) }, presets: [UniverSheetsCorePreset({ container: 'app' })], }) univerAPI.createWorkbook({})
Step 2 · Add the agent loop
Put the model outside the editor. Give it safe, observable operations.
conceptual service boundary
type Task = { workbookId: string instruction: string } async function runAgentTask(task: Task) { const state = await office.inspect(task.workbookId) const plan = await model.propose({ state, task }) await policy.check(plan) const result = await office.apply(plan) const report = await office.verify(result) return { result, report } }
A
Inspect before actGive the model structured state and relevant ranges, not an unbounded page dump.
B
Apply through commandsKeep mutations explicit, auditable and easy to roll back or review.
C
Verify the artefactValidate formulas, ranges, rendered layout and business-specific rules.
D
Escalate ambiguityAsk a person when the agent lacks confidence or the cost of a wrong edit is high.
The code is an implementation pattern, not a verbatim Univer API listing. Treat it as a product architecture guide and map each operation to documented Facade APIs and your own policy layer.
Step 3 · Extend safely
When your workflow is real, graduate from configuration to a domain plugin.
Client
Make it legible
Menus, shortcuts, status, visual warnings and custom components belong in a UI-facing plugin.
Shared
Make it reusable
Models, commands, mutations, services and Facade APIs should not depend on browser-only state.
Server
Make it automatable
Use headless paths for batch work, generation, verification and background jobs, while keeping policies around them.
Version alignmentKeep coordinated
@univerjs/* packages on the same release line.Public API disciplinePrefer documented package exports and Facade APIs over internal implementation folders.
Runtime compatibilityPlan for target browsers,
Intl.Segmenter support and your chosen build tool.Test the mutationCover command behaviour and formula correctness before layering on polished UI.
Step 4 · Validate & ship
Ship a narrow capability with a visible proof loop.
Before release
Prove the core behaviour
✓
Unit / integration testsFormula correctness, command mutations, range operations and failure paths.
✓
Rendered checksLong formulas, zoom, scrolling, keyboard paths and mobile layout.
✓
Agent evaluationGolden tasks with expected edits, provenance and human-review triggers.
After release
Keep the surface trustworthy
↺
Observe decisionsLog requested action, applied mutation, verification result and reviewer outcome.
↺
Version deliberatelyTrack package alignment and document any experimental API dependency.
↺
Make escape hatchesProvide undo, draft state, approval gates and a clear way to inspect raw content.
Done condition: a user can complete one meaningful task end to end, understand what the agent changed, and recover when the workflow goes wrong.
What to remember
Univer’s unfair advantage is not “more spreadsheet features”.
THE THESIS
It gives product teams a reusable office runtime that agents can operate and people can review.
That makes structured Office content a first-class part of your application architecture.
Best fit
AI-native workspaces, planning tools, operational dashboards, structured reviews and domain-specific document workflows.
Watch-outs
Sheets are most mature. Slides are active development. API stability, version alignment and OSS/Pro boundaries matter.
First move
Prototype one end-to-end task with preset mode, then test whether a domain plugin earns its complexity.
Sources & evidence
Read the repo, then make the product boundary your own.
01
Repository README — “Univer is an open-source SDK for creating office applications inside your own product.” Open source
02
Repository README — “One consistent API surface for workbooks, ranges, formulas, and documents across browser and Node.js.” Open source
03
Isomorphic architecture note — “Separate plugins” for underlying logic and UI; commands and mutations should not read UI state. Open source
04
Core package README — the foundation provides runtime, dependency injection, command and mutation services, data models, configuration, localisation and Facade entry points. Open source
05
Docs — Preset mode provides a shorter curated setup; plugin mode gives lower-level control; headless Univer supports Node.js processing. Documentation
06
Scope note: implementation snippets labelled “conceptual” are design patterns, not claims that those exact helper names are part of the public API. Verify against the current docs before shipping.
Licence: the repository is Apache-2.0. Product-specific Pro capabilities are documented separately and may have different commercial terms.