@haklex/rich-compose
Compose primitives for haklex rich content — Gundam-style assembly of Lexical nodes, sync/lazy renderers, edit-side decorators, and Provider stacks. Powers both composeRenderer (read-only) and composeEditor (editable).
Why
The legacy @haklex/rich-kit-shiro/renderer (now removed) shipped every default renderer eagerly: overriding CodeBlock or LinkCard left the original shiki and LinkCardRenderer chains in the bundle. rich-compose solves three problems at once:
- Subtractable — drop a module by not importing it.
- Replaceable — swap a default renderer with no leftover bytes.
- Extensible — add new renderer slots (sync or lazy) without touching the package.
Tree-shake is enforced by physical subpath isolation (./modules/<name>/node separates Klasses from heavy renderer code; ./modules/<name> vs ./modules/<name>/edit separates static-only from editor-only chains) plus ESM-only emit.
Installation
pnpm add @haklex/rich-compose
Peer Dependencies
| Package | Version |
|---|---|
react / react-dom | >=19 |
lexical / @lexical/react | ^0.45.0 |
@haklex/rich-editor | workspace |
Per-module upstream packages (@haklex/rich-ext-*, @haklex/rich-renderer-*) are optional peers — install only those you compose.
Quick start
Read-only renderer
import { composeRenderer } from '@haklex/rich-compose/core';
import { allRendererModules } from '@haklex/rich-compose/renderer';
const RichContent = composeRenderer({ modules: allRendererModules });
// Render
<RichContent value={editorState} theme="light" variant="article" />;
Or cherry-pick:
import { composeRenderer } from '@haklex/rich-compose/core';
import { embedModule } from '@haklex/rich-compose/modules/embed';
import { codeBlockModule } from '@haklex/rich-compose/modules/code-block';
const RichContent = composeRenderer({ modules: [embedModule, codeBlockModule] });
Editor
import { composeEditor } from '@haklex/rich-compose';
import { allEditorModules } from '@haklex/rich-compose/editor';
const RichEditor = composeEditor({ modules: allEditorModules });
// Use like @haklex/rich-editor's RichEditor — accepts the same props plus children for plugins.
<RichEditor initialValue={state} onChange={setState} variant="article" />;
Both helpers return memoized React components. composeEditor internally wires composeRenderer for nested editor states.
Optional renderer virtualization
Rendering remains complete by default. Enable the recycler with props:
const scrollRef = useRef<HTMLDivElement>(null);
const virtualization = useMemo(() => ({ scrollContainer: scrollRef, preserveCapacity: 32 }), []);
<ScrollArea scrollRef={scrollRef}>
<RichContent value={editorState} virtualization={virtualization} />
</ScrollArea>;
The viewport must have a bounded height. scrollContainer accepts its DOM element, a ref, or a getter; it must contain the rendered content. Without it, the recycler finds the nearest scrolling ancestor, then uses the window.
Alternatively, install the implementation as a compose module:
import { rendererVirtualizationModule } from '@haklex/rich-compose/virtualization';
const RichContent = composeRenderer({
modules: [...allRendererModules, rendererVirtualizationModule({ preserveCapacity: 32 })],
});
An explicit virtualization={false} overrides an installed module. The module supplies a rendering surface; it does not turn on a second full-document renderer. Nested renderers keep their ordinary surface unless explicitly enabled.
The editor and renderer share typed recycling pools, measured margin collapse, and the keep-mounted manager. Up to 32 offscreen mounts are retained by default; LRU eviction saves details/dynamic state before reusing an instance. Set preserveCapacity: 0 for immediate state restoration. Dynamic components need getState/setState to survive eviction; custom components can use useEditorBlock().nodeState() and retain().
Heading anchors and footnote numbering are prepared from the complete document, while React trees are created only for rendered windows. Opt-in virtual SSR emits a bounded initial window; default SSR stays complete. Float images and the flowing text through their clearing block remain one native flow unit, as does the note lead paragraph with its next block. A very large flow unit or single table is not virtualized internally. Initial parsing and document replacement still scale with document size. Changing the document, variant, or recycler options rebuilds the transient view cache. Native selection/copy across unmounted content and browser find-in-page remain limited to mounted windows.
The demo's 20,000 Complex Nodes preset supports both Edit and Render. Both use the UI ScrollArea viewport explicitly, with a fixed inspector beside it. Rendering and editing share the same article width and horizontal spacing.
Three consumer modes
Mode A — defaults
Import the module sugar. Klass + renderer + (optional) lazy/SSR fallback are wired automatically.
import { embedModule } from '@haklex/rich-compose/modules/embed';
import { embedEditModule } from '@haklex/rich-compose/modules/embed/edit';
Mode B — custom renderer (tree-shake the default)
Import the Klass from /node; supply your own renderer.
import { GalleryNode } from '@haklex/rich-compose/modules/gallery/node';
const myGalleryModule: RichRendererModule = {
name: 'gallery',
nodes: [GalleryNode],
renderers: { Gallery: MyGalleryRenderer },
};
For renderer-only modules (no custom Klass), construct with matching name:
const myLinkCardModule: RichRendererModule = {
name: 'link-card',
renderers: { LinkCard: MyLinkCardRenderer },
};
Mode C — wrap the default
Pull the default renderer from /renderer and wrap.
import { LinkCardRenderer } from '@haklex/rich-compose/modules/link-card/renderer';
const wrappedModule: RichRendererModule = {
name: 'link-card',
renderers: {
LinkCard: (props) => (
<div className="extra-wrap">
<LinkCardRenderer {...props} />
</div>
),
},
};
Module shapes
RichRendererModule (read-only) and RichEditorModule (editor superset).
interface RichRendererModule {
name: string; // dedup key
nodes?: Klass<LexicalNode>[]; // base Klasses
renderers?: Partial<RendererConfig>; // sync renderer map
Provider?: ComponentType<{ children: ReactNode }>; // shared provider
lazyRenderers?: Partial<{
[K in RendererKey]: () => Promise<{ default: NonNullable<RendererConfig[K]> }>;
}>;
ssrFallback?: Partial<Record<RendererKey, ReactNode>>;
}
interface RichEditorModule extends RichRendererModule {
editNodes?: Klass<LexicalNode>[]; // edit-side subclasses (override base by getType)
editRenderers?: Partial<RendererConfig>; // override renderers in editor mode
EditorProvider?: ComponentType<{ children: ReactNode }>; // editor-only provider
plugins?: ReactNode; // module-owned editor plugins
nestedEditorPlugins?: ReactNode; // plugins mounted inside LexicalNestedComposer surfaces
actions?: ReactNode; // module-owned action UI
}
composeRenderer consumes RichRendererModule[]; composeEditor consumes RichEditorModule[]. Each editor module spreads its renderer-only counterpart, so allEditorModules is a strict superset of allRendererModules.
Dedup rules
modules:
reference seen → skip silently
same name → warn (dev), replace previous module entirely
else → append
nodes:
reference seen → skip
subclass override → edit Klass replaces base Klass (same getType, A extends B)
unrelated collision → throw at compose time
(would break instanceof across module boundaries)
Lazy modules
code-block and mermaid ship lazy by default with deterministic ssrFallbacks. whiteboard's Klass code-splits internally via its own decorate().
To override a lazy renderer (e.g., pre-tokenized code block for SSR), pass overrides:
composeRenderer({
modules: allRendererModules,
overrides: { CodeBlock: PreTokenizedCodeBlock },
});
The lazy chunk is still emitted but never fetched at runtime.
Platform-agnostic rendering
RichRenderer (and composeRenderer) emit DOM by default, but every DOM touchpoint is injectable so the same tree walk can target another React renderer (React Native, ink, a test harness):
| Hook | Covers |
|---|---|
builtinNodeOverrides[type] | Element nodes (paragraph, heading, list, …) and decorator nodes (image, mermaid, …) |
builtinNodeOverrides.text | Text leaves — receives the serialized text node (text, format, style) |
blockAnchor(el, blockId, key) | Root-level block wrapper carrying $.blockId; defaults to a data-block-id div |
as | Host container — any ElementType; non-string hosts receive only style and children |
A decorator override receives the default decoration as its single child and may drop it:
<RichRenderer
as={View}
blockAnchor={(el, blockId, key) => (
<View key={key} nativeID={blockId}>
{el}
</View>
)}
builtinNodeOverrides={{
text: (node, key) => (
<Text key={key} style={textStyle(node.format)}>
{node.text}
</Text>
),
paragraph: (_node, key, children) => <Text key={key}>{children}</Text>,
mermaid: (node, key) => <NativeMermaid key={key} diagram={node.diagram} />,
}}
value={state}
/>
Decorator slots (rendererConfig / module renderers) accept any React component, so Image, CodeBlock, LinkCard etc. can be replaced the same way.
Module catalog
| Module | Base Klass | Edit Klass | Mode | Source |
|---|---|---|---|---|
alert | builtin | — | sync | rich-renderer-alert |
banner | builtin | — | sync | rich-renderer-banner |
chart | ChartNode | ChartEditNode | sync | rich-ext-chart |
chat | ChatNode | ChatEditNode | sync | rich-ext-chat |
code-block | builtin | — | lazy + ssr fallback | rich-renderer-codeblock |
code-snippet | CodeSnippetNode | CodeSnippetEditNode | sync | rich-ext-code-snippet |
embed | EmbedNode | EmbedEditNode | sync (via node decorate) | rich-ext-embed |
whiteboard | WhiteboardNode | WhiteboardEditNode | via node decorate | rich-ext-whiteboard |
gallery | GalleryNode | GalleryEditNode | sync | rich-ext-gallery |
image | builtin | — | sync | rich-renderer-image |
katex | — | builtin | edit-only (no static renderer) | rich-renderer-katex |
link-card | builtin | — | sync | rich-renderer-linkcard |
mention | builtin | — | sync | rich-renderer-mention |
mermaid | builtin | — | lazy + ssr fallback | rich-renderer-mermaid |
nested-doc | NestedDocNode | NestedDocEditNode | recursive (via composeRenderer) | rich-ext-nested-doc |
poll | PollNode | PollEditNode | sync | rich-ext-poll |
ruby | builtin | — | sync | rich-renderer-ruby |
video | builtin | — | sync | rich-renderer-video |
katex ships only an edit module — KaTeX rendering for the read-only side is wired by the host renderer via decorate().
Sub-path exports
| Path | Description |
|---|---|
@haklex/rich-compose | compatibility barrel: core helpers plus aggregate conveniences |
@haklex/rich-compose/core | renderer composition core: composeRenderer, RichRenderer, renderer types |
@haklex/rich-compose/renderer | aggregate barrel — every renderer module + allRendererModules |
@haklex/rich-compose/editor | aggregate barrel — every editor module + allEditorModules |
@haklex/rich-compose/modules/<name> | renderer-side module barrel |
@haklex/rich-compose/modules/<name>/edit | editor-side module (extends the renderer module) |
@haklex/rich-compose/modules/<name>/node | Klass(es) only (when applicable) |
@haklex/rich-compose/modules/<name>/renderer | default renderer only |
@haklex/rich-compose/style.css | all-in-one CSS bundle — prose body + tokens + every module |
@haklex/rich-compose/style/foundation.css | prose body + theme tokens + variant classes (no modules) |
@haklex/rich-compose/style/table.css | built-in table renderer |
@haklex/rich-compose/style/<name>.css | per-module CSS (alert, banner, image, video, …) |
Aggregate barrels are convenient defaults; the fine-grained /modules/<name> and /modules/<name>/edit subpaths stay available for dynamic-import and selective inclusion.
CSS strategy
Two consumer patterns:
All-in-one (default). One import covers everything rich-compose can render:
import '@haklex/rich-compose/style.css';
Fine-grained (advanced). Use this when you've overridden one or more default renderers and want to drop their CSS from your bundle. Import foundation.css plus the modules you keep — never reach into rich-renderer-* or rich-ext-* packages directly:
import '@haklex/rich-compose/style/foundation.css';
import '@haklex/rich-compose/style/alert.css';
import '@haklex/rich-compose/style/image.css';
import '@haklex/rich-compose/style/ruby.css';
// …only modules whose default renderer you kept
Module subpaths mirror the JS module subpaths (modules/<name> ↔ style/<name>.css).
Why not auto-injected via import side effects
Earlier versions tried to side-effect-import each module's CSS from inside modules/<name>/index.ts. Combined with sideEffects: ["**/*.css"] (which marks .mjs files as side-effect-free) and bundler optimizations such as Next.js optimizePackageImports, those bare CSS imports were tree-shaken away — modules rendered but their styling was missing. The explicit subpath model above eliminates that footgun: the consumer states which CSS they want, and the bundler honors it deterministically.
Part of Haklex
This package is part of the Haklex rich editor ecosystem.
License
MIT