# How to Enable and Use the @openmaic/editor Package: A Complete Guide

> Learn to enable and use the @openmaic/editor package. Install, import CSS, and wrap your app with EditorProvider for a powerful ProseMirror editor.

- Repository: [MAIC/OpenMAIC](https://github.com/THU-MAIC/OpenMAIC)
- Tags: how-to-guide
- Published: 2026-09-10

---

**To enable and use the `@openmaic/editor` package, install it via your package manager, import the CSS bundle from [`dist/editor.css`](https://github.com/THU-MAIC/OpenMAIC/blob/main/dist/editor.css), wrap your application with the `EditorProvider` component from `@openmaic/editor/react`, and render the `<Editor>` component to create a fully functional ProseMirror-based editing surface.**

The `@openmaic/editor` package provides the core editing infrastructure for the OpenMAIC project, delivering a modular ProseMirror-based editing system with dedicated sub-modules for core schema management, React component bindings, and UI utilities. Located in the `packages/@openmaic/editor` directory of the THU-MAIC/OpenMAIC repository, this package enables developers to integrate rich text and mathematical content editing into OpenMAIC-based applications through a flexible, extension-ready architecture.

## Installing and Enabling the Package

Begin by installing the package into your project. The OpenMAIC repository uses a PNPM workspace, but the package functions with any Node.js package manager:

```bash

# Using pnpm (recommended for monorepo development)

pnpm add @openmaic/editor

# Using npm or yarn

npm install @openmaic/editor

```

After installation, import the required stylesheet to ensure proper rendering of editor UI elements. The package bundles a minimal CSS file at [`dist/editor.css`](https://github.com/THU-MAIC/OpenMAIC/blob/main/dist/editor.css) that must be loaded before rendering any components:

```tsx
import '@openmaic/editor/dist/editor.css';

```

## Package Architecture and Entry Points

The `@openmaic/editor` package is organized into three sub-modules that can be imported independently or together, each serving distinct architectural purposes as defined in the [`package.json`](https://github.com/THU-MAIC/OpenMAIC/blob/main/package.json) manifest:

**`@openmaic/editor/core`** – Located in `src/core/`, this module exposes the low-level ProseMirror schema, transaction handling logic, and document model. It defines the fundamental node types (text, math, images) and the `EditorTransaction` type for type-safe document manipulation.

**`@openmaic/editor/react`** – Found in `src/react/`, this module provides ready-to-use React components including `EditorProvider`, `Editor`, and `useEditorContext`. These components manage the ProseMirror `EditorView` lifecycle and expose the transactional API to React child components.

**`@openmaic/editor/ui`** – Housed in `src/ui/`, this module contains UI utilities such as element clipboard handling via `useClipboard` and DOM helpers. It implements the `openmaic/editor-elements` clipboard kind used throughout the suite for standardized copy-paste operations.

## Basic React Implementation

Wrap your application root with `EditorProvider` to inject the editor context, then render the `Editor` component where needed:

```tsx
import { EditorProvider, Editor } from '@openmaic/editor/react';
import '@openmaic/editor/dist/editor.css';

function App() {
  return (
    <EditorProvider>
      <div className="workspace">
        <Editor placeholder="Start typing…" />
      </div>
    </EditorProvider>
  );
}

```

The `EditorProvider` initializes the ProseMirror `EditorView` instance and maintains the editor state, while the `Editor` component renders the actual contenteditable surface pre-configured with the OpenMAIC schema.

## Working with the Transaction API

For programmatic document manipulation, access the core transaction API through the React context hook:

```tsx
import { useEditorContext } from '@openmaic/editor/react';
import type { EditorTransaction } from '@openmaic/editor/core';

function InsertMathButton() {
  const { view } = useEditorContext();

  const insertEquation = () => {
    const tr: EditorTransaction = view.state.tr;
    const mathNode = view.state.schema.nodes.math.create({ content: 'E=mc^2' });
    view.dispatch(tr.replaceSelectionWith(mathNode));
  };

  return <button onClick={insertEquation}>Insert Math</button>;
}

```

The `EditorTransaction` type provides strong typing for ProseMirror's transaction API, ensuring safe read and write operations against the document model defined in `src/core/`.

## UI Utilities and Clipboard Operations

The UI sub-module exposes specialized hooks for handling complex clipboard operations, particularly for rich content elements:

```tsx
import { useClipboard } from '@openmaic/editor/ui';

function CopySelectionButton() {
  const { copySelection } = useClipboard();

  return <button onClick={copySelection}>Copy Selection</button>;
}

```

Implementation details for these utilities reside in [`src/ui/elementClipboard.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/src/ui/elementClipboard.ts), which coordinates with the `openmaic/editor-elements` clipboard kind to preserve formatting during copy-paste cycles.

## Extending the Editor Schema

To support custom node types, import the base schema from the core module and extend it before passing to the provider:

```tsx
import { EditorProvider } from '@openmaic/editor/react';
import { schema as baseSchema } from '@openmaic/editor/core';

const extendedSchema = baseSchema.extend({
  nodes: {
    highlight: {
      group: 'inline',
      inline: true,
      selectable: true,
      toDOM: () => ['span', { class: 'highlight' }, 0],
      parseDOM: [{ tag: 'span.highlight' }],
    },
  },
});

function App() {
  return (
    <EditorProvider schema={extendedSchema}>
      <Editor />
    </EditorProvider>
  );
}

```

This pattern allows the editor to accommodate domain-specific content types while maintaining compatibility with OpenMAIC's transaction system.

## Testing and Verification

The package includes comprehensive validation suites to ensure schema integrity and component reliability. Key test files include:

- **[`tests/packages/editor-manifest.test.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/tests/packages/editor-manifest.test.ts)** – Validates the publication manifest and package exports defined in `packages/@openmaic/editor/package.json`
- **[`tests/edit/surfaces/slide/renderer-editor-architecture.test.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/tests/edit/surfaces/slide/renderer-editor-architecture.test.ts)** – Verifies integration between the editor and slide rendering surfaces, ensuring the ProseMirror view coordinates correctly with OpenMAIC's workspace shell

Run these tests using your workspace test runner to confirm proper editor initialization before deployment.

## Summary

- **Install** `@openmaic/editor` via pnpm, npm, or yarn, then import [`dist/editor.css`](https://github.com/THU-MAIC/OpenMAIC/blob/main/dist/editor.css) to enable styling.
- **Structure** your application with `EditorProvider` at the root to establish the ProseMirror context for child components.
- **Import** from three distinct sub-modules—`core` for schema/transaction logic, `react` for UI components, and `ui` for clipboard utilities—depending on your use case.
- **Extend** the base schema using the `schema.extend()` method to add custom node types while preserving type safety.
- **Test** integrations using the provided manifest and surface architecture tests located in `tests/packages/` and `tests/edit/surfaces/slide/`.

## Frequently Asked Questions

### What is the difference between `@openmaic/editor/core` and `@openmaic/editor/react`?

`@openmaic/editor/core` exports the underlying ProseMirror schema, transaction types, and document model logic found in `src/core/`. `@openmaic/editor/react` provides React bindings including the `EditorProvider` context wrapper and `Editor` component from `src/react/`. Use core for headless document manipulation or non-React environments; use react for standard React application integration.

### How do I style the editor components?

Import the base stylesheet `import '@openmaic/editor/dist/editor.css'` in your application entry file. This CSS bundle ensures proper rendering of ProseMirror elements, node selections, and UI chrome. You can layer additional custom styles on top of these base rules to match your application's design system.

### Can I use `@openmaic/editor` without React?

Yes. While the package provides React bindings for convenience, the core editing engine in `@openmaic/editor/core` is framework-agnostic ProseMirror code. You can instantiate the schema and transaction API directly from `src/core/` and bind the resulting `EditorView` to any DOM container using vanilla JavaScript or alternative frameworks.

### Where are the editor tests located in the repository?

Test coverage includes [`tests/packages/editor-manifest.test.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/tests/packages/editor-manifest.test.ts) for package configuration validation and [`tests/edit/surfaces/slide/renderer-editor-architecture.test.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/tests/edit/surfaces/slide/renderer-editor-architecture.test.ts) for integration testing within slide editing surfaces. These files verify that the editor correctly initializes and coordinates with OpenMAIC's workspace infrastructure.