Plate
PlateEditorsTemplates
GitHub16kGitHub
DiscordDiscord
  • Feature Kits
  • Plugin
    • Plugin Methods
    • Plugin Shortcuts
    • Plugin Context
    • Plugin Components
    • Plugin Rules
    • Editing Behavior
    • Plugin Input Rules
  • Editor
    • Editor Methods
    • Controlled Value
  • Authored Changes
  • Performance
  • Static Rendering
  • HTML
  • Markdown
  • Form
  • TypeScript
  • Debugging
  • Unit Testing
  • Browser
  • Troubleshooting
  • Locations
  • Transactions
  • Serializing
  • Roots
  • Document Meta
  • Clipboard and Paste
  • Decorations, annotations, and widgets
  • Schema
  • History
  • Pagination
  • Annotations
  • DOM Coverage
  • External Text Views
  • Virtualized Rendering

Debugging

PreviousNext

Debugging in Plate.

Using the DebugPlugin

The DebugPlugin is automatically included when you create a Plate editor. You can access its methods through the editor's API:

const editor = createEditor({
  plugins: [/* your plugins */],
});
 
editor.api.debug.log('This is a log message');
editor.api.debug.info('This is an info message');
editor.api.debug.warn('This is a warning');
editor.api.debug.error('This is an error'
TypeScriptUnit Testing

On This Page

Using the DebugPluginLog levelsInitial stateError handlingBest practicesAdditional debugging strategies1. Inspect committed changes2. Remove suspected plugins3. Use React DevTools4. Use browser DevTools breakpoints5. Create minimal reproducible examples6. Use Redux DevTools for zustand storesDebug error typesScrubbing values
Build your editor
Production-ready AI template and reusable components.
Get all-access
);
const editor = createEditor({
  plugins: [/* your plugins */],
});
 
editor.api.debug.log('This is a log message');
editor.api.debug.info('This is an info message');
editor.api.debug.warn('This is a warning');
editor.api.debug.error('This is an error');

Log levels

The DebugPlugin supports four log levels:

  1. log: For general logging
  2. info: For informational messages
  3. warn: For warnings
  4. error: For errors

You can set the minimum log level to control which messages are displayed:

const editor = createEditor({
  plugins: [
    DebugPlugin.configure({
      initialState: {
        logLevel: 'warn', // Only show warnings and errors
      },
    }),
  ],
});
const editor = createEditor({
  plugins: [
    DebugPlugin.configure({
      initialState: {
        logLevel: 'warn', // Only show warnings and errors
      },
    }),
  ],
});

Initial state

Seed the DebugPlugin store with these fields:

  • isProduction: Set to true to disable logging in production environments.
  • logLevel: Set the minimum log level ('error', 'warn', 'info', or 'log').
  • logger: Provide custom logging functions for each log level.
  • throwErrors: Set to true to throw errors instead of logging them (default: true).

Example configuration:

const editor = createEditor({
  plugins: [
    DebugPlugin.configure({
      initialState: {
        isProduction: process.env.NODE_ENV === 'production',
        logLevel: 'info',
        logger: {
          error: (message, type, details) => {
            // Custom error logging
            console.error(`Custom Error: ${message}`, type, details);
          },
          // ... custom loggers for other levels
        },
        throwErrors: false,
      },
    }),
  ],
});
const editor = createEditor({
  plugins: [
    DebugPlugin.configure({
      initialState: {
        isProduction: process.env.NODE_ENV === 'production',
        logLevel: 'info',
        logger: {
          error: (message, type, details) => {
            // Custom error logging
            console.error(`Custom Error: ${message}`, type, details);
          },
          // ... custom loggers for other levels
        },
        throwErrors: false,
      },
    }),
  ],
});

Error handling

By default, the DebugPlugin throws errors when error is called. You can catch these errors and handle them as needed:

try {
  editor.api.debug.error('An error occurred', 'CUSTOM_ERROR', { details: 'Additional information' });
} catch (error) {
  if (error instanceof EditorError) {
    console.debug(error.type); // 'CUSTOM_ERROR'
    console.debug(error.message); // '[CUSTOM_ERROR] An error occurred'
  }
}
try {
  editor.api.debug.error('An error occurred', 'CUSTOM_ERROR', { details: 'Additional information' });
} catch (error) {
  if (error instanceof EditorError) {
    console.debug(error.type); // 'CUSTOM_ERROR'
    console.debug(error.message); // '[CUSTOM_ERROR] An error occurred'
  }
}

To log errors instead of throwing them, set throwErrors to false in the configuration.

Best practices

  1. Use appropriate log levels for different types of messages.
  2. In production, set isProduction to true to disable non-essential logging.
  3. Use custom loggers to integrate with your preferred logging service.
  4. Include relevant details when logging to make debugging easier.
  5. Use error types to categorize and handle different error scenarios.

Additional debugging strategies

Besides using the DebugPlugin, there are other effective ways to debug your Plate editor:

1. Inspect committed changes

Subscribe to commits when you need to inspect editor writes. Each commit exposes the canonical DocumentChange, tags, version, and changed-state queries without patching editor methods:

const editor = createEditor({
  plugins: [],
});
 
const unsubscribe = editor.subscribeCommit((commit) => {
  console.debug('Editor commit:', {
    change: commit.changes.toJSON(),
    documentChanged: commit.changed.has('document'),
    tags: commit.tags,
    version: commit.version,
  });
});
 
// Call this when the debugging session ends.
unsubscribe();
const editor = createEditor({
  plugins: [],
});
 
const unsubscribe = editor.subscribeCommit((commit) => {
  console.debug('Editor commit:', {
    change: commit.changes.toJSON(),
    documentChanged: commit.changed.has('document'),
    tags: commit.tags,
    version: commit.version,
  });
});
 
// Call this when the debugging session ends.
unsubscribe();

Use editor.subscribe(...) instead when the listener also needs the current snapshot. For a reusable editing policy, contribute a Plate command handler or correction through the constructor's root commands or corrections field and test that behavior directly.

2. Remove suspected plugins

If you're experiencing issues, try removing plugins one by one to isolate the problem:

const editor = createEditor({
  plugins: [
    // Comment out or remove suspected plugins
    // HeadingPlugin,
    // BoldPlugin,
    // ...other plugins
  ],
});
const editor = createEditor({
  plugins: [
    // Comment out or remove suspected plugins
    // HeadingPlugin,
    // BoldPlugin,
    // ...other plugins
  ],
});

Gradually add plugins back until you identify the one causing the issue.

3. Use React DevTools

React DevTools can be invaluable for debugging Plate components:

  1. Install the React DevTools browser extension.
  2. Open your app and the DevTools.
  3. Navigate to the Components tab.
  4. Inspect Plate components, their props, and state.

4. Use browser DevTools breakpoints

Set breakpoints in your code using browser DevTools:

  1. Open your app in the browser and open DevTools.
  2. Navigate to the Sources tab.
  3. Find your source file and click on the line number where you want to set a breakpoint.
  4. Interact with your editor to trigger the breakpoint.
  5. Inspect variables and step through the code.

5. Create minimal reproducible examples

If you're facing a complex issue:

  1. Pick a template.
  2. Add only the essential plugins and components to reproduce the issue.
  3. If the issue persists, open an issue on GitHub or share your example on Discord.

6. Use Redux DevTools for zustand stores

Zustand and thus zustand-x works with the Redux DevTools browser extension. It can be very useful to help track state changes in zustand stores.

Follow the zustand documentation to get going with Redux DevTools and zustand.

Debug error types

editor.api.debug.error(message, type, details) uses the supplied type as a log prefix. In development, enabling throwErrors makes it throw an EditorError; the default type is DEFAULT. You can supply an application-specific string for your own diagnostics.

Plugin setup also validates descriptors, dependencies, and schema ownership:

MessageCheck
USE_CREATE_PLUGINCreate plugins with definePlugin from the appropriate entrypoint.
Pass a plugin descriptor, not its name.Put descriptors in dependencies, not strings.
requires disabled pluginKeep required dependencies enabled.
Circular plugin dependencyRemove the dependency cycle shown in the error.
cannot declare both schema.element and schema.markGive each plugin one schema role.

Dependencies are installed from their descriptors. A required dependency does not need a duplicate entry in the application's plugin list.

Scrubbing values

Plate redacts text in formatted error details. Install a value scrubber when other document fields also need redaction:

import { setDebugValueScrubber } from 'platejs';
 
setDebugValueScrubber((key, value) => {
  if (key === 'text' || key === 'src') return '[redacted]';
  return value;
});
import { setDebugValueScrubber } from 'platejs';
 
setDebugValueScrubber((key, value) => {
  if (key === 'text' || key === 'src') return '[redacted]';
  return value;
});

The callback has type (key: string, value: unknown) => unknown and runs before default text redaction. Returning the original value preserves that default processing. Pass null or undefined to restore the default scrubber.