AGENTS.md

Guidance for AI agents working in this repository. Downstream users of the package should read https://editor.lobehub.com/skills.md and https://editor.lobehub.com/llms.txt instead.

Overview

@lobehub/editor is a Lexical-based rich text editor for React: a framework-agnostic kernel, 20+ plugins, React components (Editor, ChatInput, ...), a headless entry and a read-only renderer. The docs site (https://editor.lobehub.com) is built with @lobehub/docs-kit (lobedocs) from the index.mdx files next to the source.

Key paths:

Using Skills

Skills live in .agents/skills/<name>/SKILL.md. Read the whole SKILL.md (and any reference/ files it links) before starting a task that matches it, then follow it.

Notes:

• These skills are for maintainers. skills.md and llms.txt on the docs site are generated by lobedocs build for downstream users; do not edit them by hand.
• Each SKILL.md starts with YAML frontmatter (name, description), so skill CLIs can discover them; check with npx skills add ./ --list from the repo root.

Writing Docs

Follow .agents/skills/using-docs-kit/SKILL.md. Repo specifics:

• Location: one index.mdx per documented folder. docs.config.ts sets atomDirs to src/react, src/plugins and src/renderer, so src/plugins/hr/index.mdx becomes /components/plugins/hr and src/react/SendButton/index.mdx becomes /components/react/send-button. Only files named index.mdx are picked up (index.md is ignored).
• Frontmatter: title, description (one or two plain sentences; it feeds search, SEO and llms.txt) and category. Reuse existing categories: Core, Plugins (plugins); General, Data Entry, Layout, Playground, Providers (React); Renderer. Do not add dumi fields (nav, group, atomId).
• Demos: put them in <folder>/demos/ (index.tsx for the basic one), one export default component each, importing the library by package name (@lobehub/editor, @lobehub/editor/react); docs.config.ts aliases it to src. Reference them with import DemoIndex from './demos/index.tsx?demo'; and <Demo of={DemoIndex} />. Use editable={false} for editor playgrounds, layout="bare" for full-width ones, isolated for demos that use portals or global CSS.
• Structure: start at ## (the title is the H1); typical sections are ## Introduction, ## Basic Usage, then features, then ## APIs with property tables (| Property | Description | Type | Default |). This repo writes API tables by hand; keep them in sync with the TypeScript types.
• Preview: pnpm dev (alias of lobedocs dev; restart it after editing docs.config.ts). pnpm docs:build runs every docs validation (frontmatter, demo references, broken links).
• Do not hand-edit compatibility.json (legacy URL inventory) unless you move or rename an existing page; the build checks that every legacy URL is still produced.
• Changes that affect users also go in README.md only if they change installation or the quick-start example; the README links to the docs site for everything else.

Adding a New Plugin / Component

Plugin (src/plugins/<name>/)

Use an existing plugin as the template: hr (small decorator node), collapsible (element node with commands, Markdown and LiteXML), toc (service + hooks, no node).

1. Node — node/<Name>Node.ts: the custom Lexical node and $create… / $is… helpers.
2. Commands — command/index.ts: createCommand<Payload>('INSERT_…_COMMAND') plus a register…Command(editor) function returning a cleanup.
3. Kernel plugin — plugin/index.ts: export const <Name>Plugin: IEditorPluginConstructor<Options> = class extends KernelPlugin implements IEditorPlugin<Options> with a unique static pluginName. In the constructor call kernel.registerNodes([...]), kernel.registerThemes({...}) and, for decorator nodes, this.registerDecorator(...). In onInit(editor) wrap registrations in this.register(...).
4. Markdown — in onInit, this.kernel.requireService(IMarkdownShortCutService) then registerMarkdownShortCut / registerMarkdownWriter / registerMarkdownReader (see src/plugins/hr/plugin/index.ts, src/plugins/collapsible/plugin/index.ts).
5. LiteXML — this.kernel.requireService(ILitexmlService) then registerXMLWriter(nodeType, …) and registerXMLReader(tagName, …), so AI edits and the headless export round-trip the node.
6. React plugin — react/React<Name>Plugin.tsx, react/type.ts (props with JSDoc), react/style.ts (createStaticStyles from @lobehub/ui), react/index.ts(x) exporting React<Name>Plugin and export type * from './type'.
7. Services (optional) — service/ with a genServiceId token, registered via kernel.registerService (see src/plugins/toc/service/i-toc-service.ts).
8. Strings — add user-facing text to src/locale/index.ts; read it with useTranslation() from @/editor-kernel/react/useTranslation in React code, or kernel.t(...) in the kernel plugin.
9. Logging — createDebugLogger('plugin', '<name>') from @/utils/debug; no bare console.log.
10. Barrel — src/plugins/<name>/index.ts exports the commands, plugin and React plugin.
11. Entries — add export * from './plugins/<name>'; to src/index.ts. If the node must survive server-side processing, add the kernel plugin to DEFAULT_HEADLESS_EDITOR_PLUGINS in src/headless/index.ts. If saved content should render read-only, add the node class to src/renderer/nodes/index.ts and a renderer in src/renderer/renderers/, registered in createDefaultRenderers() (src/renderer/renderers/index.ts).
12. Demo & docs — demos/index.tsx + index.mdx (see Writing Docs). Also wire the plugin into the playground src/react/Editor/demos/index.tsx when it is user-visible.
13. Tests — Vitest + jsdom, colocated in __tests__/ (*.test.ts(x)), e.g. src/plugins/toc/__tests__/. Cover commands, Markdown and LiteXML round-trips; headless behaviour goes in src/headless/__tests__/.

React component (src/react/<Component>/)

Mirror src/react/SendButton/: <Component>.tsx, type.ts (props with JSDoc), style.ts, index.ts (export { default } from './<Component>'; export * from './type';), demos/index.tsx, index.mdx, and __tests__/ when there is logic. Export it from src/react/index.ts (export { default as <Component>, type <Component>Props } from './<Component>';).

New public entry (rare)

A new subpath needs both an exports entry in package.json and an entry in tsdown.config.ts (the browser build lists index, react, renderer, codemirror; the node build lists headless and shared chunks). Run pnpm build to confirm the output.

Before you finish

pnpm type-check
pnpm lint          # ESLint --fix on src and tests
pnpm lint:circular # dpdm, fails on circular imports
pnpm vitest run    # or scope it: pnpm vitest run src/plugins/<name>
pnpm docs:build    # when you touched docs or demos

Conventions & Checks

• Package manager: pnpm (packageManager: pnpm@10.20.0). There is no lockfile (.npmrc sets lockfile=false); do not add one. If type-check fails on missing exports from @lobehub/ui etc., your node_modules is stale: run pnpm install.
• Scripts (package.json): dev / docs:dev, docs:build, build, test, test:coverage, lint, lint:style, lint:md, lint:circular, type-check, ci (lint:circular + lint + type-check), prettier, demo:yjs-server, verify:node-identity-package.
• Imports: use the @/ alias for src/ inside the library; demos import from @lobehub/editor.
• Commits: gitmoji + Conventional Commits, lowercase scope, e.g. ✨ feat(table): add column resize, 🐛 fix: …, 📝 docs: … (checked by commitlint via @lobehub/lint).
• Hooks: .husky/pre-commit runs type-check (skipped when CI=true), lint:circular and lint-staged (Prettier, ESLint, Stylelint, remark on staged files). Never bypass hooks with --no-verify; fix the failure instead.
• Release: semantic-release (release.config.js, .github/workflows/release.yml) publishes from master; do not bump version or edit CHANGELOG.md by hand.
• .cursor/rules/ expand on this file (project structure, plugin and React patterns, hotkeys, debug logging, docs). Keep them in sync: when you change a convention here, update the matching rule too.