lobe-editor / rules

---
description: Coding standards and conventions for LobeHub Editor
globs: *.ts,*.tsx,*.js,*.jsx
---

# Coding Standards

Lint and format rules are enforced by `eslint.config.js`, `prettier.config.js` and
`stylelint.config.js` (all from `@lobehub/lint`); the pre-commit hook runs them on staged files.
This rule covers conventions the tools do not check.

## TypeScript

- `tsconfig.json` is `strict`; prefer explicit types over `any` in public APIs.
- Public kernel / plugin interfaces live in [src/types/](mdc:src/types/) (`IEditor`,
  `IEditorKernel`, `IEditorPlugin`, `IEditorPluginConstructor`, `IServiceID`, ...).
- Naming:
  - `I` prefix for service interfaces and their ids: `IMarkdownShortCutService`, `ILitexmlService`.
  - `<Name>Props` for React props, `<Name>PluginOptions` / `<Name>Options` for kernel plugin
    options, `Serialized<Name>Node` for node JSON.
  - Commands are `SCREAMING_SNAKE_CASE` and end with `_COMMAND`.
- Use `import type` / inline `type` imports for type-only imports.

## Imports

```typescript
// External packages first
import { mergeRegister } from '@lexical/utils';
import type { LexicalEditor } from 'lexical';

// Internal modules via the @/ alias (maps to src/)
import { KernelPlugin } from '@/editor-kernel/plugin';
import type { IEditorKernel } from '@/types';
import { createDebugLogger } from '@/utils/debug';

// Relative imports last
import { MyNode } from '../node/MyNode';
import { styles } from './style';
```

- Library code uses `@/…`; demos and docs import the public package names
  (`@lobehub/editor`, `@lobehub/editor/react`).
- Avoid circular imports: `pnpm lint:circular` (dpdm) fails the pre-commit hook on them.

## React Components

```tsx
'use client';

import { cx } from '@lobehub/ui';
import type { FC } from 'react';

import { styles } from './style';
import type { MyComponentProps } from './type';

const MyComponent: FC<MyComponentProps> = ({ className, children, ...rest }) => {
  return (
    <div className={cx(styles.root, className)} {...rest}>
      {children}
    </div>
  );
};

MyComponent.displayName = 'MyComponent';

export default MyComponent;
```

- `FC` + default export + `displayName`. Use `memo` only when it pays off and leave a comment
  saying why (`// Keep memo: ...`, see `src/react/Editor/Editor.tsx`).
- Styles in `style.ts` with `createStaticStyles` from `@lobehub/ui` (no CSS files, no
  `antd-style` hooks). Details in [react-development](mdc:.cursor/rules/react-development.mdc).

## Kernel Code

- Mutate editor state only inside `editor.update(...)`; command handlers return `true` when
  handled.
- Register listeners through `this.register(...)` / `mergeRegister` so they are cleaned up.
- Log with `createDebugLogger` (see [debug-logging](mdc:.cursor/rules/debug-logging.mdc)), not
  bare `console.*`; for errors that must always surface use `prodSafeLogger.error`.

## Tests

- Vitest with `globals: true` and the `jsdom` environment (`vitest.config.ts`); import
  `describe` / `it` / `expect` / `vi` from `vitest` explicitly.
- Colocate tests in `__tests__/` as `*.test.ts(x)` (a few older folders use `__test__`).
- React tests render with `createRoot` + `act` from React (no Testing Library dependency),
  see `src/react/SendButton/__tests__/`.
- Run: `pnpm test` (watch), `pnpm vitest run <path>`, `pnpm test:coverage`.

## JSDoc

Document public props and exported functions with JSDoc; for props include `@default` when
there is one. These comments are the source for the hand-written API tables in `index.mdx`.

## File Naming

- Directories: kebab-case for plugins (`link-highlight`), PascalCase for React component
  folders (`src/react/SendButton`).
- Components and React plugins: PascalCase files (`SendButton.tsx`, `ReactHRPlugin.tsx`).
- Nodes: PascalCase (`node/HorizontalRuleNode.ts`).
- Other modules: kebab-case or camelCase, matching neighbouring files (`i-upload-service.ts`,
  `registerHotkey.ts`).
- Folder entry is `index.ts`; props in `type.ts`; styles in `style.ts`.