Suneditor React Component

Common errors

• ReferenceError: document is not defined

  cause Attempting to render `SunEditor` on the server-side in an SSR environment (e.g., Next.js) without disabling SSR for the component.
  fix Wrap the `SunEditor` component with `next/dynamic` and set `ssr: false`. Example: `const SunEditor = dynamic(() => import('suneditor-react'), { ssr: false });`

• Error: Element type is invalid: expected a string (for built-in components) or a class/function (for composite components) but got: undefined. You likely forgot to export your component from the file it's defined in, or you might have mixed up default and named imports.

  cause Forgetting to install the `suneditor` core package, which `suneditor-react` depends on, or an incorrect import statement.
  fix Ensure both `suneditor` and `suneditor-react` are installed (`npm install suneditor suneditor-react`) and that `SunEditor` is imported correctly as a default import: `import SunEditor from 'suneditor-react';`

• Cannot read properties of undefined (reading 'setContents')

  cause Attempting to call methods on the `SunEditor` core instance (e.g., `setContents`, `getContents`) before it has been initialized or when the ref is not correctly pointing to the instance.
  fix Use the `getSunEditorInstance` prop to obtain the core SunEditor object and store it in a `useRef` hook. Ensure you check if the ref's `current` value is available before attempting to call methods on it.

Warnings

• breaking The order of parameters for `onImageUploadBefore`, `onVideoUploadBefore`, and `onAudioUploadBefore` event handlers was fixed.
  Fix: Review and adjust the parameter order in your callback functions for these specific upload events if you are upgrading from an earlier version and using these props. Refer to the official SunEditor documentation for the correct signature.
• gotcha The `suneditor` core package is a peer dependency and must be installed separately alongside `suneditor-react`.
  Fix: Ensure you run `npm install --save suneditor suneditor-react` or `yarn add suneditor suneditor-react` when setting up the package.
• gotcha When using Server-Side Rendering (SSR) frameworks like Next.js, importing `SunEditor` directly will cause 'document is not defined' errors during build or server-side execution.
  Fix: Always use Next.js's `dynamic` import with `ssr: false` to ensure the component is only loaded on the client-side. Refer to the 'Next.js' section in the package's README.
• gotcha Accessing the underlying SunEditor instance (the 'core' object) directly from event callbacks is not supported by `suneditor-react`. You need to use the `getSunEditorInstance` prop.
  Fix: Pass a callback function to the `getSunEditorInstance` prop and store the returned `sunEditor` instance in a `useRef` hook. You can then interact with the core editor methods via this ref.
• gotcha For optimal performance, especially with many plugins, it's recommended to load only the plugins you need.
  Fix: Override the `plugins` option within the `setOptions` prop to specify an array of desired plugin names. If `plugins` is not specified, all default plugins are loaded.

Install

• npm install suneditor-react npm
• yarn add suneditor-react yarn
• pnpm add suneditor-react pnpm

Imports

• SunEditor
  wrong:

  const SunEditor = require('suneditor-react');

  correct:

  import SunEditor from 'suneditor-react';

  Primarily designed for ESM imports in modern React applications. CommonJS 'require' might lead to bundling issues or incorrect module resolution, especially in build environments expecting ESM.
• SunEditor CSS

  import 'suneditor/dist/css/suneditor.min.css';

  The core SunEditor CSS must be imported manually to style the editor. Forgetting this will result in an unstyled, broken-looking editor.
• SunEditor (Next.js)
  wrong:

  import SunEditor from 'suneditor-react';

  correct:

  import dynamic from 'next/dynamic';
  const SunEditor = dynamic(() => import('suneditor-react'), { ssr: false });

  When using Next.js or other SSR frameworks, SunEditor must be dynamically imported with `ssr: false` to prevent 'document is not defined' errors during server-side rendering, as the editor relies on browser APIs.
• SunEditorCore (TypeScript)

  import SunEditorCore from 'suneditor/src/lib/core';

  For TypeScript users who need to type the underlying SunEditor instance (e.g., when using `getSunEditorInstance` with `useRef`), import `SunEditorCore` directly from the `suneditor` package for accurate type hints.

Quickstart

This example demonstrates how to integrate `suneditor-react` into a Next.js application using dynamic imports, access the underlying SunEditor instance via a ref, set initial content, and handle content changes.

import React from 'react';
import dynamic from 'next/dynamic';
import 'suneditor/dist/css/suneditor.min.css'; // Import Sun Editor's CSS File

// Important: Dynamic import for Next.js to disable SSR
const SunEditor = dynamic(() => import('suneditor-react'), {
  ssr: false,
});

const MyRichTextEditor = () => {
  const editorRef = React.useRef();

  // The sunEditor parameter will be set to the core suneditor instance
  const getEditorInstance = (sunEditor) => {
    editorRef.current = sunEditor;
    if (editorRef.current) {
      console.log('SunEditor instance ready:', editorRef.current);
      // Example: Set initial content programmatically
      // editorRef.current.setContents('<p>Hello from <b>suneditor-react</b>!</p>');
    }
  };

  const handleEditorChange = (content) => {
    console.log('Editor content changed:', content);
  };

  return (
    <div>
      <h1>My Blog Post Editor</h1>
      <SunEditor
        getSunEditorInstance={getEditorInstance}
        onChange={handleEditorChange}
        setOptions={{
          height: '200px',
          buttonList: [['undo', 'redo'], ['font', 'fontSize', 'formatBlock'], ['bold', 'underline', 'italic', 'strike'], ['align', 'list'], ['image', 'link']],
          lang: 'en' // Example language setting
        }}
        defaultValue="<p>Start typing your content here...</p>"
      />
      <button onClick={() => console.log('Current content:', editorRef.current?.getContents())}>
        Log Current Content
      </button>
    </div>
  );
};

export default MyRichTextEditor;