Entry points
The package entry points of edytor, what each exports, and where each can run, from the browser to Node and Cloudflare Workers, plus the Notion theme stylesheet.
The edytor package has five code entry points and one stylesheet. Only the root contains Svelte components; the other entries have no Svelte in their import graph and run in Node and in Cloudflare Workers.
| Import | Contains | Runs in |
|---|---|---|
edytor |
The <Edytor> component, bundled plugins, handles, the document API, sync factories |
A Svelte bundler (SvelteKit, Vite) |
edytor/crdt/edytor |
The document API and its full vocabulary, bindCrdt, awareness, attribution, migration |
Browser, Node 22+, Workers |
edytor/export |
toHTML, toMarkdown, fromHTML, fromMarkdown, textToBlocks, mdxComponent and the bundled kinds’ forms (Import and export) |
Browser, Node 22+, Workers |
edytor/protocol |
The wire vocabulary: frames, message types, codecs, generation records, the admission gates, the raw provider classes | Browser, Node 22+, Workers |
edytor/crdt |
The vendored CRDT engine itself (Yjs v14 fork) | Browser, Node 22+, Workers |
edytor/cloudflare |
DocumentRoom (a Durable Object), attachRoom (for your own Durable Object), routeDocumentSocket with requestedReplica, routeDocumentHistory (the version history), routeDocumentComments (the comment threads), and closedSocket |
Cloudflare Workers only |
edytor/themes/notion.css |
The Notion theme stylesheet | Any bundler that imports CSS |
No other path is exported. Imports such as edytor/dist/... or edytor/crdt/vendor/... fail with ERR_PACKAGE_PATH_NOT_EXPORTED.
Every name each entry exports, with its declaration, is listed in the API report the repository keeps under api/ (one file per entry point). A change to it is reviewed like code: the unit tests fail until the report is regenerated.
edytor
The root entry is what a Svelte app imports:
import {
Edytor, // the component
useEdytor, // the editor instance from inside the component tree
Block, Text, InlineBlock, // handle classes
createRichTextPlugin, createSuggestionsPlugin, // the default plugins
createArrowMovePlugin, // block moves from the keyboard, listed by the app
createImagePlugin,
textToBlocks, // a string or markdown as blocks (suggestions)
createCodePlugin, createMarkdownShortcutsPlugin,
createSlashMenuPlugin, createToolbarPlugin, createBlockMenuPlugin, createBlockHandlesPlugin,
richTextOperations, richTextPlaceholder, convertToKind,
createDocument, loadDocument, attachDocument, // the document API
createIndexeddbSync, createWebsocketSync, clearDocument // sync factories
} from 'edytor';
It also exports what a Svelte app needs of edytor/crdt/edytor: the document factories and class, their errors (SchemaMismatchError, SyncRefusedError, …), defaultSemantics and semanticsOf, the JSON types (JSONDoc, JSONBlock, JSONText, JSONInlineBlock) and the command results (OpResult, Plan, Prepared, DocChange). The rest of the document’s vocabulary (BlockSpec, Destination, ProjectedDoc, DocAnchor, toBlockSpec, …) is imported from edytor/crdt/edytor, which a Svelte app can import too.
Because it contains .svelte files, the root entry needs a bundler that compiles Svelte. Plain Node cannot import it.
edytor/crdt/edytor
The same document surface without Svelte. Use it on a server, in a script, in a worker or anywhere the component cannot load:
import { createDocument, loadDocument } from 'edytor/crdt/edytor';
// The bundled kinds' block roles (`defaultSemantics`) by default: no view supplies them here.
const document = createDocument({
value: { children: [{ type: 'paragraph', content: [{ text: 'hello' }] }] },
actor: { id: 'user-42', name: 'Ada' }
});
const [block] = document.project().children;
document.transact(() => document.insertText(block.id, 5, ' world'));
const saved = document.encode(); // Uint8Array
const restored = loadDocument(saved);
console.log(restored.toJSON());
It exports:
createDocument,loadDocument,attachDocumentand theEdytorDocumentclass. See the document reference.- The JSON and document types:
JSONDoc,JSONBlock,JSONText,JSONInlineBlock,BlockSpec,Destination,OpResult,DocChange,DocAnchor,DocPosition,RangeView,FlowView,EdytorDoc, andtoBlockSpec. - The block roles:
defaultSemantics,semanticsOfand the bundled kinds’ tables. Awareness, the sync types (EdytorSync,WebsocketSyncOptions, …), the errors a load or a sync refuses with, and attribution types.bindCrdt(Y), which binds the providers, migration and sync protocol to an engine you pass in.
The ready-made sync factories (createIndexeddbSync, createWebsocketSync) are exported from the root, the provider classes from edytor/protocol. Outside Svelte, reach the providers through bindCrdt:
import * as Y from 'edytor/crdt';
import { bindCrdt } from 'edytor/crdt/edytor';
const crdt = bindCrdt(Y);
const doc = crdt.createDoc();
const awareness = new crdt.Awareness(doc);
const provider = new crdt.providers.IndexeddbPersistence('document-id', doc, { awareness });
await provider.whenSynced;
edytor/export
A document as HTML or Markdown and back, by each kind’s own forms, with no Svelte: use it in a server route, a Worker or a script (Import and export).
import { toMarkdown } from 'edytor/export';
console.log(toMarkdown({ children: [{ type: 'heading', content: [{ text: 'Hello' }] }] }));
edytor/protocol
The wire and coordinator vocabulary, for code that speaks the protocol itself: a server of your own, a relay, a test client, tooling that drives a provider.
import { frame, messageSync, writeVarUint8Array } from 'edytor/protocol';
const message = frame(messageSync, (encoder) => writeVarUint8Array(encoder, new Uint8Array()));
It exports:
bindCrdt(Y)and the engine typings it speaks;- the frame contract (
frame,GENERATION,generationWord,readProtocolVersion, the generation records), the message types (messageSync,messageAwareness,messageSaved,messageChunk, …), the chunk codec and the close codes (CLOSE); - the lib0 helpers that read and write frame bodies, and the awareness codec that needs no
Awarenessinstance; - the admission gates (
assertAdmission,inspectAdmission,checkSchema, …); - the raw provider classes behind the sync factories,
IndexeddbPersistenceandWebsocketProvider, with their option and event types, andstoreState.
See the protocol for the contract.
edytor/crdt
The raw engine: Edytor’s own fork of Yjs v14, pruned to what Edytor uses (documents, nodes, transactions, the update encoding and merging, state vectors, relative positions).
import * as Y from 'edytor/crdt';
export const merge = (updateA: Uint8Array<ArrayBuffer>, updateB: Uint8Array<ArrayBuffer>) => Y.mergeUpdates([updateA, updateB]);
You rarely need it directly. Reach for it when you pass the engine to bindCrdt, or when you handle raw updates (merging, state vectors) yourself.
edytor/cloudflare
The server side of real-time collaboration: DocumentRoom, a Durable Object that coordinates one document; attachRoom(this, options), which hosts a document in any Durable Object of yours; routeDocumentSocket, which authorizes a client before its WebSocket upgrade, and requestedReplica, which reads the client id the dial sends; and closedSocket(code, reason), which turns a dial away from your own Worker with a close the provider understands (see authorization).
import { DocumentRoom, routeDocumentSocket, requestedReplica } from 'edytor/cloudflare';
export { DocumentRoom };
It imports cloudflare:workers, so it loads only inside a Worker. It is built on the Worker-safe CRDT entries and has no Svelte or DOM code. Setup is covered in Server quick start and Your own Durable Object. Its attachDocument is unrelated to the attachDocument of edytor, which wraps an engine document on the client.
Bundle size and tree-shaking
- Import what you render. Every JavaScript module in the package is free of side effects (
sideEffectslists only CSS), so a bundler drops the plugins you never import. The code plugin, with TanStack Highlight and its stylesheet, ships only in apps that importcreateCodePlugin. - The engine is pruned.
edytor/crdtis Edytor’s fork of Yjs v14, cut down to what Edytor runs on. The document API reaches the engine through one fixed object of the symbols it calls, so an app that never importsedytor/crdtitself bundles only what those symbols reach.bindCrdt(Y)with the whole namespace (import * as Y from 'edytor/crdt') keeps the whole pruned engine. - Headless code stays small.
edytor/crdt/edytorhas no Svelte and no view code: a server route or Worker that reads and edits documents does not pull in the editor. - One engine. Never add the
yjspackage next to Edytor: it is a second, incompatible engine.
Choosing an entry
- Rendering an editor:
edytor. - Reading, converting or editing a document in Node, a SvelteKit server route or a Worker:
edytor/crdt/edytor. - Exporting a document as HTML or Markdown, or importing either, anywhere:
edytor/export. - Speaking the wire protocol yourself, or driving a raw provider:
edytor/protocol. - Handling raw updates, or passing the engine to
bindCrdt:edytor/crdt. - Hosting collaboration on Cloudflare:
edytor/cloudflare. - Notion’s look for the document:
import 'edytor/themes/notion.css'.