Facade API — How the Web SDK Improves the Development Experience

In this post, we will discuss the Facade API, the interface layer of the Web SDK, and how it improves usability and serves a broader audience of developers.

Design Goals of the Web SDK

From the outset, the architecture of the Web SDK was built with the following goals in mind:

1. Flexible extension of non-core functionalities through a plugin system to support user customization and community-driven plugin development.
2. High customizability and scalability to meet the needs of complex applications.
3. Long-term maintainability and testability for large projects.
4. Providing an excellent developer experience.

To achieve these goals, we introduced various mechanisms, such as the plugin system, dependency injection, and a command system. However, these mechanisms also introduced some side effects: the complexity of directly using the Web SDK's low-level APIs made development less accessible, which conflicted with our goal of providing a "great developer experience."

Fortunately, as the saying goes, "All problems in computer science can be solved by another level of indirection". We addressed this issue by introducing the Facade API as the interface layer of the Web SDK. This abstraction layer encapsulates internal complexities, offering users a straightforward and intuitive API.

The Simplicity of the Facade API

Using the Facade API is incredibly simple. If you use Univer Presets, we automatically create a univerAPI for you, allowing you to start developing immediately:

const { univerAPI } = createUniver({  locale: LocaleType.EN_US,  locales: {    [LocaleType.EN_US]: mergeLocales(UniverPresetSheetsCoreEnUS),  },  presets: [    UniverSheetsCorePreset({      container: 'app',    }),  ],})const sheet = univerAPI.getActiveWorkbook().getActiveSheet()const range = sheet.getRange('A1')range.setValue('Hello, Univer!')

Extensible Interface Design

In the initial implementation of the Facade API, all functionalities were centralized in a single @univerjs/facade package. However, this led to several issues:

1. Code hints for plugins appeared in the API even if the plugins weren’t imported, disrupting the development experience.
2. Plugins not in use were still included in the user’s build due to references in the Facade API implementation, resulting in unnecessary bloat.

To address these issues, we restructured the Facade API.

First, we introduced interface classes, extension mixins, and an extension mechanism. Interface classes represent the original Facade API types (e.g., FUniver, FWorkbook) and inherit from FBase. FBase provides a static extend method for adding extension mixins. These mixins are essentially TypeScript classes that enhance the interface classes with additional methods.

Next, we modularized the interfaces. For example, FWorksheet was split into several files:

• packages/sheets/src/facade/f-worksheet.ts: Defines the FWorksheet interface class.
• packages/sheets-ui/src/facade/f-worksheet.ts: Implements UI-related extensions for worksheets.
• packages/sheets-filter/src/facade/f-worksheet.ts: Implements filtering extensions.
• packages/sheets-data-validation/src/facade/f-worksheet.ts: Implements data validation extensions.

This modular approach ensures that each file only contains APIs related to a specific plugin, reducing unnecessary dependencies and keeping functionalities distinct.

We also enhanced TypeScript’s IntelliSense. Using the declare keyword, we informed TypeScript of extended interface class types. For instance, the sheets-ui package includes the following code:

FWorksheet.extend(FWorksheetSkeletonMixin)declare module '@univerjs/sheets/facade' {  interface FWorksheet extends IFWorksheetSkeletonMixin {}}

Finally, we introduced secondary entry points for all packages that provide a Facade API, allowing users to import APIs more selectively. For example, to use the Facade API from sheets-ui, users can import it as follows:

import '@univerjs/sheets-ui/facade'

These optimizations resolved the previous issues:

1. Developers only see relevant API hints for the packages they’ve imported.
2. Only necessary code is bundled into the final output, avoiding unnecessary overhead.

Universal Support for Browsers and Node.js

During a recent refactor, we standardized each plugin’s runtime environment, reusing as much code as possible between browsers and Node.js. You can now run the Web SDK in Node.js for server-side reading, writing, and computations, or even as a headless collaborative client in a Univer-powered editing system.

The Facade API supports both browser and Node.js environments. The main exception is packages ending in -ui, which are browser-exclusive.

From an Embedded Editor to a Complete Office Application

The Facade API is the application-facing layer of the Web SDK runtime. It keeps integration code centered on workbooks, worksheets, ranges, documents, and UI extensions rather than internal services. A team can start with one embedded editor workflow and keep the same API model as the application grows.

A typical integration can grow in stages:

1. Start with a preset, obtain univerAPI, and implement content operations through Facade objects.
2. Add only the plugin Facade entry points needed for features such as UI, filtering, or data validation.
3. Reuse browser-independent APIs in Node.js for headless reading, writing, and calculations.
4. When the product needs self-hosted collaboration or an Agent entry point, compose the runtime with Univer Collaboration SDK or AI SDK.

The documentation is organized into Web SDK, Server SDK, and AI SDK, covering editor APIs, collaboration and file exchange, and agent workflows.

Continuously Enhancing Facade API

Our engineers are constantly improving the Facade API with new features. Its extension model lets each package add APIs alongside the corresponding capability, so coverage can grow without pulling unrelated functionality into every build.

We’re also simplifying the developer experience. Presets register the Facade APIs needed by the selected features, so most integrations do not have to import every @univerjs/xxx/facade entry manually. We continue to improve the guides and API reference so developers can discover and use the available APIs more easily.

Today, we explored the design and implementation of the Facade API, as well as our ongoing efforts to enhance its usability and functionality. The Facade API gives developers an approachable application layer while preserving the Web SDK’s modular architecture. As the SDK evolves, it will continue to help teams build tailored Office experiences, from a focused embedded editor to a complete application.

For those unfamiliar with the Univer Office SDK: It is a full-stack development framework supporting browser and server-side creation and editing of spreadsheets and documents. It enables seamless integration of Office applications into various web systems. The core architecture and features of the Web SDK are open source on GitHub.

Author: Wenzhao Hu , Tech Lead & Architect