CKEditor 5 Custom Online Build

Common errors

• ReferenceError: ClassicEditor is not defined

  cause The CKEditor 5 build script (`ckeditor.js`) was not loaded, or was loaded incorrectly, before attempting to initialize the editor.
  fix Ensure that `<script src="./build/ckeditor.js"></script>` is correctly placed in your HTML, preferably right before the script that calls `ClassicEditor.create()`, and that the path to `ckeditor.js` is correct. Verify `npm run build` ran successfully.

• Module not found: Error: Can't resolve 'ckeditor5-custom-build'

  cause Attempting to `import` or `require` the `ckeditor5-custom-build` package directly as a module, rather than using its generated output or the underlying CKEditor 5 source modules.
  fix This package is a *source* repository for a build. You should import the *generated output* from your `build/` directory (e.g., `import ClassicEditor from './path/to/build/ckeditor.js';`) or load it via a `<script>` tag.

• License key is missing.

  cause A premium CKEditor 5 feature is being used without a valid license key provided in the editor's configuration.
  fix Obtain a license key from CKEditor.com and pass it in the editor configuration: `ClassicEditor.create( element, { licenseKey: 'YOUR_LICENSE_KEY' } )`.

• Error: The editor was initialized without the `config.collaboration.channelId`.

  cause Real-time collaboration features are enabled in the build, but the required `channelId` (and potentially `webSocketUrl`) is missing from the editor's configuration.
  fix Provide the necessary collaboration configuration: `ClassicEditor.create( element, { collaboration: { channelId: 'my-document-id', webSocketUrl: 'ws://localhost:3000' } } )`.

Warnings

• gotcha This package is a *template* for a custom build, not a pre-built library. To use it, you must first run `npm install` and then `npm run build` to compile the editor bundle into the `build/` directory. Direct usage of `ckeditor5-custom-build` via `npm install ckeditor5-custom-build` does not provide a ready-to-use editor.
  Fix: After cloning or downloading the custom build, navigate to its directory and run `npm install && npm run build`. Then, integrate the generated files from the `build/` directory into your application.
• breaking As of March 2025 (Q1 2025), predefined CKEditor 5 builds (like `ckeditor5-build-classic`) and the legacy Online Builder, which this package emanates from, were deprecated. New installation methods focus on direct npm packages (`@ckeditor/ckeditor5`) and browser builds. While existing custom builds still function, future updates or new custom builds are encouraged to use the updated builder and installation methods.
  Fix: For new projects or major upgrades, consider migrating to the latest CKEditor 5 installation methods that utilize `npm` packages directly (e.g., `@ckeditor/ckeditor5`) instead of relying on custom build repositories from the deprecated online builder.
• gotcha If your custom build includes premium CKEditor 5 features (e.g., real-time collaboration, export to PDF/Word, certain advanced plugins), you will need a valid license key or specific backend endpoints. Without them, premium features will not function, and you may encounter console warnings.
  Fix: Obtain the necessary license key or backend service endpoints from CKEditor.com and ensure they are correctly configured during editor initialization, typically via the `config` object passed to `ClassicEditor.create()`.
• gotcha The README explicitly warns about browser caching issues after rebuilding the editor. Changes to the build might not reflect immediately in the browser.
  Fix: After running `npm run build`, perform a hard refresh in your browser (Ctrl + R or Cmd + R) or clear your browser's cache to ensure the latest editor bundle is loaded.
• gotcha The FAQ mentions that the online builder (and thus builds generated from it) is 'Not yet' directly usable with common frameworks like React, Vue, or Angular, though integrations are planned. While technically possible to integrate, this means official, streamlined wrappers or direct component usage are not provided out-of-the-box by this custom build template itself.
  Fix: For framework integration, developers typically need to create their own wrappers or components that import the generated `build/ckeditor.js` bundle and initialize the editor manually within the framework's lifecycle. Official CKEditor 5 documentation provides guides for framework integration.

Install

• npm install ckeditor5-custom-build npm
• yarn add ckeditor5-custom-build yarn
• pnpm add ckeditor5-custom-build pnpm

Imports

• ClassicEditor
  wrong:

  import { ClassicEditor } from 'ckeditor5-custom-build';

  correct:

  <script src="./build/ckeditor.js"></script>
  <script>
    ClassicEditor
      .create( document.querySelector( '#editor' ) )
      .then( editor => {
        console.log( 'Editor was initialized', editor );
      } )
      .catch( error => {
        console.error( error.stack );
      } );
  </script>

  This package is the *source* for a custom build. The `ClassicEditor` (or other editor type) constructor is exposed as a global variable by the *generated* `build/ckeditor.js` file, which is typically loaded via a script tag in HTML. Direct `import` from `ckeditor5-custom-build` itself is not the intended usage.
• Editor instance
  wrong:

  const Editor = require('ckeditor5-custom-build').Editor;

  correct:

  import ClassicEditor from './build/ckeditor.js'; // Assuming a ClassicEditor build
  
  ClassicEditor
    .create( document.querySelector( '#editor' ) )
    .then( editor => {
      // The editor instance itself, useful for advanced integrations.
      window.editor = editor;
    } )
    .catch( error => {
      console.error( 'Error initializing editor', error );
    } );

  For module-based applications (e.g., React, Vue, Angular), the *bundled output* (`build/ckeditor.js`) can be imported directly as an ESM module, which then exposes the editor constructor as its default export. The CommonJS `require` pattern is not typically used for CKEditor 5 builds.

Quickstart

This quickstart demonstrates how to include and initialize a custom CKEditor 5 classic build in a basic HTML page. It assumes the project has been built via `npm run build`, creating `build/ckeditor.js` and `build/ckeditor.css`.

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>CKEditor 5 Custom Build Quickstart</title>
    <!-- The editor CSS can be bundled or linked directly -->
    <link rel="stylesheet" href="./build/ckeditor.css">
</head>
<body>
    <h1>My Custom CKEditor 5 Instance</h1>

    <div id="editor">
        <p>This is the initial content of the editor.</p>
    </div>

    <script src="./build/ckeditor.js"></script>
    <script>
        ClassicEditor
            .create( document.querySelector( '#editor' ), {
                // Optional: Your license key if using premium features
                // licenseKey: process.env.CKEDITOR_LICENSE_KEY ?? '',

                // Optional: Configuration for real-time collaboration
                // collaboration: {
                //     channelId: 'my-document-id',
                //     webSocketUrl: 'ws://localhost:3000',
                //     uploadUrl: 'http://localhost:3000/upload'
                // }
            } )
            .then( editor => {
                window.editor = editor;
                console.log( 'CKEditor 5 ClassicEditor was successfully initialized!', editor );
            } )
            .catch( error => {
                console.error( 'There was a problem initializing the editor.', error );
                console.error( 'Error details:', error.message );
            } );
    </script>
</body>
</html>