🌅 Sunset of old installation methods: timelines and next steps

[Witoso]

With the release of CKEditor 5 v42.0.0, we introduced a new installation experience designed to simplify and improve the developer workflow. As part of this transition, we are phasing out older installation methods that have become outdated or incompatible with modern development practices. Here are the updated timelines and our next steps.

A brief reminder of currently available installation methods:

• New installation methods:
  • Published in the 42.0.0 version (released July 2024).
  • Provide many improvements: work well with all modern bundlers (i.e. bundler-agnostic), decoupled styles from the JavaScript layer.
  • Two ways of self-hosted setup:
    • aggregated packages: Use two packages that include everything, for easy onboarding.
    • optimized way: Use individual packages for size-tuned builds.
  • Two ways of cloud (CDN) hosting:
    • UMD globals.
    • ESM (import maps).
• Old installation methods:
  • Consists of several methods of setting up the editor pre-42.0.0:
    • Predefined builds: usage of packages like ckeditor5-build-classic , provided with a fixed set of plugins to use.
    • Custom builds: coupled with the webpack build step, also delivered as an output in the old builder. Imports happened through specific packages with features.
    • DLLs: advanced method used for dynamic editor creation and configuration on the browser side, is now covered by browser builds out-of-the-box.
  • Each method had its pros and cons, but together they didn’t create a coherent proposal, and integrators had a constant trouble with them.

If you’re interested in our reasoning about those past changes, feel free to explore the main GitHub issue: #15502 , release blog post, and related documentation.

Timelines

Initially, we planned to deprecate most of the methods in Q1, but we decided to prolong the support for the custom builds to give you more time to migrate.

• End of Q1, 2025:
  • Predefined builds (e.g ckeditor5-build-classic) will be officially deprecated.
    • No new versions of predefined builds packages will be published to npm.
    • The documentation for these setups will be removed from our docs.
    • See the proposed migration path.
  • We will update our environment to target ES2022, officially dropping support for webpack v4.
    • ⚠️ This will affect setups that use old installation methods (i.e., custom builds).
    • Technically, the projects that have webpack 4 will still be able to use the new version, but some additional configuration may need to be added. It depends on the project setup.
    • New installation methods already use ES2022, so projects already using them will not be impacted.
• End of 2025:
  • Custom builds (webpack-dependent builds) will be officially deprecated.
    • New npm package versions will no longer include the src directory. Instead, the dist directory will become the primary entry point for importing files, and all imports will happen through the package’s index.
    • Deprecation of the @ckeditor/ckeditor5-dev-translations package, which will no longer be needed.
    • Still to be decided, but we may deprecate loading translations from the CKEDITOR_TRANSLATIONS global, as new installation methods enable and promote doing it through the editor’s configuration.
    • See the proposed migration path.
  • DLL (webpack dependent) will be officially deprecated.
    • Documentation for DLLs will be removed.
    • New npm package versions will no longer include the build directory.
    • See the proposed migration path.

Work in progress

While deprecating these older methods, we are actively working on several enhancements to further improve CKEditor 5 migration to new installation methods:

1. Improved icon customization (Allow icon customization without webpack-specific plugins #16546)

   We are exploring better support for icon customization in the new installation methods. Two possible approaches are being considered:

   • Overriding icons via editor configuration, similar to translations.
   • Importing icons from a dedicated package and allowing developers to override them using npm or yarn resolutions.

2. Improved index exports (🧩 Missing imports after update to v42.0.0+ #17289)

   We are addressing issues related to missing exports and ensuring better compatibility with new installation methods. We are reviewing all requests for missing imports to determine which should be included in the public API. This effort aims to prevent runtime errors and improve the overall developer experience.

Questions? Let us know!

We encourage the CKEditor community to share feedback and ask questions as we navigate these changes. Your input is invaluable in shaping a smoother migration path and ensuring our solutions address real-world use cases.

Here’s how you can contribute:

• Share your experiences about deprecation of older methods, and migration experience.
• Let us know about any missing imports or other API gaps you’ve encountered in the new installation methods.
• Provide feedback on the proposed approaches for icon customization and enhanced exports.

We are committed to making this transition as seamless as possible and ensuring CKEditor 5 continues to meet your needs. Thank you for your understanding and support!