āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā ā š shadcn/directory/udecode/plate/(guides)/debugging ā āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā
āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā
ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā
The DebugPlugin is automatically included when you create a Plate editor. You can access its methods through the editor's API:
const editor = createPlateEditor({
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');
The DebugPlugin supports four log levels:
log: For general logginginfo: For informational messageswarn: For warningserror: For errorsYou can set the minimum log level to control which messages are displayed:
const editor = createPlateEditor({
plugins: [
DebugPlugin.configure({
options: {
logLevel: 'warn', // Only show warnings and errors
},
}),
],
});
The DebugPlugin can be configured with the following options:
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 = createPlateEditor({
plugins: [
DebugPlugin.configure({
options: {
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,
},
}),
],
});
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 PlateError) {
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.
isProduction to true to disable non-essential logging.Besides using the DebugPlugin, there are other effective ways to debug your Plate editor:
You can use the extendEditor option to override editor methods and add logging:
const LoggingPlugin = createPlatePlugin({
key: 'logging',
}).overrideEditor(({ editor, tf: { apply } }) => ({
transforms: {
apply(operation) {
console.debug('Operation:', operation);
apply(operation);
},
},
}));
const editor = createPlateEditor({
plugins: [LoggingPlugin],
});
This approach allows you to log operations, selections, or any other editor behavior you want to inspect.
If you're experiencing issues, try removing plugins one by one to isolate the problem:
const editor = createPlateEditor({
plugins: [
// Comment out or remove suspected plugins
// HeadingPlugin,
// BoldPlugin,
// ...other plugins
],
});
Gradually add plugins back until you identify the one causing the issue.
React DevTools can be invaluable for debugging Plate components:
Set breakpoints in your code using browser DevTools:
If you're facing a complex issue:
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.
Plate uses several predefined error types to help identify specific issues during development. Here's a list of these error types and their descriptions:
A general error that doesn't fit into other specific categories. Used when no other error type is applicable to the situation.
Thrown when an attempt is made to access an undefined plugin option. This occurs when trying to use a plugin option that hasn't been set or is undefined.
Indicates that an expected override is missing in a plugin configuration. This happens when a plugin expects certain overrides to be provided, but they are not present in the configuration.
Occurs when a required plugin dependency is not found. This error is thrown when a plugin depends on another plugin that hasn't been registered or included in the editor configuration.
Indicates an attempt to use a plugin that hasn't been registered. This happens when trying to access or use a plugin that is not part of the current editor configuration.
Thrown when a plugin wasn't created using createSlatePlugin or createPlatePlugin function. This error occurs when a plugin is added to the editor without being properly created using the designated function.
Indicates that the useElement hook is being used outside of the appropriate element context. This occurs when trying to access element-specific data or functionality outside of the correct component context.
Thrown when a plugin is incorrectly configured as both an element and a leaf. This error occurs when a plugin's configuration contradicts itself by setting both isElement and isLeaf to true.
ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā
āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā