🌅 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 if you used webpack 4 (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!

[cbrandtbuffalo]

We (Request Tracker developers) have been reviewing the new build options. We still prefer to build a UMD for maximum compatibility. We also try to align with GPL 2 principles by providing the original source code in RT along with the steps to re-build the editor. This allows end users to potentially modify the code themselves and rebuild it for use with RT.

With the updates, it seems "custom builds" will be deprecated and the recommended UMD options are to use pre-generated files, either via CDN or pre-generated zip file. Since you are still generating the UMD builds to create these options for each release, are the build scripts you use to create these available? Then we could just mirror your build process, making it possible for developers to still have access to un-minimized and un-treeshaken code.

[Witoso]

Just to maybe clear some confusion, "custom builds" will be removed in a way that src folder we distribute in the npm packages won't be present anymore. The src doesn't have a UMD code, it's a JavaScript source code (transpiled from TypeScript) that is "webpack-dependant", meaning you need to use webpack to properly build it. But the output of the webpack build was up to the integrator, our examples, if I recall correctly, showed UMD.

If you want to still use UMD:

1. Use our ESM-first packages to create a UMD build process by yourself with any bundler of your choice.
2. Use already published UMD, ckeditor5 npm package in dist/browser has UMD builds.
3. Mirror our build process, which we keep in the ckeditor5-dev packages. Two things to keep in mind here. First, we are using npm packages from the next tag, to not break the old installation methods. Second, this has a different versioning than the editor, we may introduce breaking changes, so be aware that you are dependent on our tools which can change any moment.

Let me know if something is unclear.

[cbrandtbuffalo]

Thanks for the additional details. As we're considering options 1 and 3, we're leaning toward 3 since it seems following your general process has the best chance of working in a way that is consistent with what ckeditor is doing. And thank you for the pointers to the build process and the important caveats.