Oasis Editor

Oasis Editor is a browser-based document editor built for applications that need more than a textarea: paged editing, rich formatting, tables, import/export workflows, command-driven UI, and a plugin surface that can grow with your product.

It ships as a TypeScript package with a vanilla embed API, React and Vue adapters, a headless runtime, public command and plugin primitives, and a CSS bundle you can import into your app.

Why Oasis

• Embed-first API: mount the editor into any DOM node and receive a stable OasisEditorClient.
• Command-driven runtime: execute built-in or plugin commands from your own buttons, menus, shortcuts, or app chrome.
• Paged document UI: use a document shell with toolbar, menubar, canvas editing, persistence hooks, and import/export flows.
• Plugin-ready architecture: register commands, toolbar items, menubar items, keymaps, lifecycle hooks, and dependencies.
• Typed package surface: core document types, editor state, toolbar registries, menu registries, command refs, and UI primitives are exported.
• Framework-friendly: use the vanilla API directly or mount through the React and Vue adapters.

Installation

npm install oasis-editor

Import the stylesheet once in your application entry:

import "oasis-editor/style.css";

Quick Start

import { createOasisEditor } from "oasis-editor";
import "oasis-editor/style.css";

const root = document.getElementById("editor");

if (!root) {
  throw new Error("Missing editor root");
}

const client = createOasisEditor(root, {
  ui: {
    shell: "document",
  },
  runtime: {
    onReady(editorClient) {
      editorClient.commands.execute("find");
    },
  },
});

await client.ready;

client.on("change", (state) => {
  console.log("Document changed", state);
});

The returned client is the public integration handle for the mounted editor:

await client.ready;

client.commands.execute("bold");
client.commands.canExecute("insertTable");
client.commands.state("bold");

const state = client.getState();
const document = client.getDocument();

client.document.update((current) => ({
  ...current,
  metadata: { ...current.metadata, title: "Draft" },
}));

client.selection.get();
client.focus.focus();
client.history.undo();
await client.export.docx();

client.document.markClean();
client.dispose();

React

import { OasisEditor } from "oasis-editor/react";
import "oasis-editor/style.css";

export function EditorScreen() {
  return (
    <OasisEditor
      ui={{ shell: "document" }}
      onClient={(client) => {
        client.on("change", (state) => {
          console.log(state.document);
        });
      }}
    />
  );
}

The React adapter is mount-only. If you need to apply a new editor configuration, remount the component.

Vue

<script setup lang="ts">
import { OasisEditor } from "oasis-editor/vue";
import "oasis-editor/style.css";
</script>

<template>
  <OasisEditor
    :config="{ ui: { shell: 'document' } }"
    :on-client="(client) => client.commands.execute('find')"
  />
</template>

The Vue adapter follows the same mount-only configuration contract as React.

Headless Runtime

Use Editor.create() when you need the runtime without the full UI shell:

import { Editor } from "oasis-editor";

const editor = await Editor.create({
  plugins: [],
});

editor.commands.execute("selectAll");

For embedded applications, prefer createOasisEditor(). It mounts the UI and returns the same command-oriented client surface used by external integrations.

Commands

Commands are the integration boundary for Oasis. Built-ins, plugins, toolbar items, menubar items, and keymaps all dispatch through command names or command refs.

import { OASIS_BUILTIN_COMMANDS, type OasisBuiltinCommand } from "oasis-editor";

const command: OasisBuiltinCommand = "insertTable";

if (client.commands.canExecute(command)) {
  client.commands.execute(command, { rows: 3, columns: 4 });
}

console.log(OASIS_BUILTIN_COMMANDS);

Common built-in commands include formatting commands such as bold, italic, underline, layout commands such as insertTable, setFontSize, setPageMargins, and document commands such as importDocument, exportDocx, and exportPdf.

Plugins

Plugins can register commands, toolbar items, menubar items, keymaps, dependencies, and lifecycle hooks.

import type { OasisPlugin } from "oasis-editor";

export const TimestampPlugin: OasisPlugin = {
  name: "Timestamp",
  commands: {
    insertTimestamp: {
      execute: () => new Date().toISOString(),
      refresh: () => ({ isEnabled: true }),
    },
  },
  toolbar: [
    {
      id: "timestamp-toolbar-button",
      command: "insertTimestamp",
      group: "insert",
      icon: "clock-3",
    },
  ],
  menubar: [
    {
      id: "timestamp-menu-item",
      path: "Insert/Timestamp",
      command: "insertTimestamp",
      shortcut: "Ctrl+Alt+T",
    },
  ],
  keymaps: [{ key: "Ctrl+Alt+T", command: "insertTimestamp" }],
};

Register plugins when mounting:

createOasisEditor(root, {
  runtime: {
    plugins: [TimestampPlugin],
  },
});

See docs/plugin-api.md for the plugin contract.

Plugin UI

Native Oasis plugin UI uses Solid primitives from oasis-editor/ui:

import { Button, Dialog, DialogFooter, TextField } from "oasis-editor/ui";

export function PluginDialog(props: { open: boolean; onClose: () => void }) {
  return (
    <Dialog
      isOpen={props.open}
      title="Plugin"
      onClose={props.onClose}
      footer={
        <DialogFooter>
          <Button variant="primary">Apply</Button>
        </DialogFooter>
      }
    >
      <TextField label="Name" onChange={(value) => console.log(value)} />
    </Dialog>
  );
}

Toolbar And Menubar Customization

Customize the toolbar and menubar after built-ins and plugin contributions are registered:

import { createOasisEditor, OASIS_TOOLBAR_ITEMS } from "oasis-editor";

createOasisEditor(root, {
  ui: {
    toolbar: {
      layout: "wrap",
    },
  },
  runtime: {
    customizeToolbar(registry) {
      registry.remove(OASIS_TOOLBAR_ITEMS.footnote);
      registry.move(OASIS_TOOLBAR_ITEMS.insertTable, {
        before: OASIS_TOOLBAR_ITEMS.link,
      });
      registry.register({
        id: "timestamp-toolbar-button",
        type: "button",
        label: "Insert timestamp",
        command: "insertTimestamp",
        tab: "plugins",
        group: "automation",
        ribbonGroupResize: {
          priority: 30,
          compactMinWidth: 120,
          collapsedIcon: "clock-3",
        },
      });
    },
    customizeMenubar(registry) {
      registry.register({
        id: "tools-timestamp",
        path: "Tools/Timestamp",
        command: "insertTimestamp",
      });
    },
  },
});

Toolbar registries support register, insertBefore, insertAfter, replace, remove, and move.

Ribbon groups resize automatically in ribbon view. Integrators can tune a group's resize priority, compact width, collapsed width, collapsed icon, and allowed states with ribbonGroupResize on any item in that group.

Package Exports

import {
  createOasisEditor,
  Editor,
  OASIS_MENU_ITEMS,
  OASIS_TOOLBAR_ITEMS,
  MenuRegistry,
  createToolbarRegistry,
  type EditorDocument,
  type EditorState,
  type DocumentPersistence,
  type ImportProgressState,
  type OasisEditorClient,
  type OasisPlugin,
} from "oasis-editor";

import "oasis-editor/style.css";

Published subpaths:

• oasis-editor: vanilla embed API, headless runtime, public types, plugins, commands, and UI primitives.
• oasis-editor/style.css: packaged editor stylesheet.
• oasis-editor/ui: Solid UI primitives for plugin authors.
• oasis-editor/react: React adapter.
• oasis-editor/vue: Vue adapter.

Local Development

Install dependencies:

npm install

Start the Vite development app:

npm run dev

Build the package and demo app:

npm run build

Build only the library package:

npm run build:lib

Run tests:

npm test

Run type checking:

npx tsc --noEmit

Useful focused validation while changing public API, plugins, or package exports:

npx tsc --noEmit
npm test -- src/__tests__/core/clientApi.test.ts src/__tests__/core/editorPluginIntegration.test.ts src/__tests__/core/pluginCollection.test.ts src/__tests__/ui/registry.test.ts
npm run build:lib

Documentation

• Client API
• Plugin API

Status

Oasis is under active development. The public client, command, toolbar, menubar, plugin, and package surfaces are being stabilized around real embed use cases. Prefer documented APIs over internal files under src/.