lobe-editor / rules

---
description: Debug logging standards and usage guidelines for LobeHub Editor
---

# Debug Logging Standards

LobeHub Editor uses the [debug](https://www.npmjs.com/package/debug) package. All helpers live
in [src/utils/debug.ts](mdc:src/utils/debug.ts).

## Usage

```typescript
import { createDebugLogger } from '@/utils/debug';

const logger = createDebugLogger('plugin', 'my-plugin'); // namespace: lobe-editor:plugin:my-plugin

logger.debug('Processing data'); // lobe-editor:plugin:my-plugin (alias: logger.log)
logger.info('Plugin initialized'); // lobe-editor:plugin:my-plugin:info
logger.warn('Deprecated option'); // lobe-editor:plugin:my-plugin:warn  -> console.warn
logger.error('Operation failed:', error); // lobe-editor:plugin:my-plugin:error -> console.error
```

`warn` / `error` use the native console methods (for dev tool filtering) but, like `debug` /
`info`, only print when their namespace is enabled.

Common categories:

```typescript
// Kernel plugins
createDebugLogger('plugin', 'link');
// Services
createDebugLogger('service', 'markdown');
// React code
createDebugLogger('react');
```

`debugLoggers` provides ready-made loggers for `demo`, `file`, `image`, `kernel`, `markdown`,
`math`, `mention`, `plugin`, `react`, `service`, `slash` and `upload`.

## Other Helpers

- `devConsole.{log,info,warn,error}`: plain console output only when
  `process.env.NODE_ENV === 'development'` (`isDev`). Use it in demos.
- `prodSafeLogger`: `error` / `warn` always print; `debug` / `info` go through the kernel logger.
- `browserDebug.enable(namespaces = 'lobe-editor:*')`, `browserDebug.disable()`,
  `browserDebug.getConfig()`, `browserDebug.showCategories()`: toggle and inspect logging in the
  browser via `localStorage.debug`.

## Enabling Output

```bash
# Node (tests, headless): DEBUG environment variable (see .env.example)
DEBUG=lobe-editor:*
DEBUG=lobe-editor:kernel,lobe-editor:plugin:*
DEBUG=lobe-editor:*,-lobe-editor:demo
DEBUG=lobe-editor:*:error,lobe-editor:*:warn
```

```javascript
// Browser console
localStorage.debug = 'lobe-editor:*'; // then reload
```

## Namespaces in Use

- `lobe-editor:kernel`
- `lobe-editor:plugin:<name>` (e.g. `markdown`, `litexml`, `link`, `image`, `upload`, `math`)
- `lobe-editor:service:<name>` (e.g. `markdown`, `slash`, `node-identity`)
- `lobe-editor:react`, `lobe-editor:react-plugin:<name>`
- Top-level categories from `debugLoggers` (`lobe-editor:upload`, `lobe-editor:demo`, ...)

## Rules

1. Library code uses `createDebugLogger` (or `debugLoggers`), not bare `console.log`.
2. Demo files may use `devConsole`.
3. `info` for major events, `warn` for recoverable issues, `error` for failures, `debug`
   sparingly for tracing.
4. Keep messages short and avoid logging inside hot loops.