Migration guide from v10.0.0 to v11.0.0

[Reinmar]

We migrated from webpack@3 to webpack@4 which means major changes in webpack.config.js and new major releases of CKEditor 5 build tools.

We also changed the structure of build repositories which means that upgrading your custom builds will not be a no-brainer this time.

---

Upgrading your custom build

The changes which we have done to the structure of build repositories touched all the files and if you maintain your custom build, merging changes from the upstream is not feasible due to the number of conflicts. Instead, we recommend starting from the stable branch of the original build repository and applying your customizations once again.

What changes?

build-config.js is gone

We completely removed the build-config.js file. Its job is now fully taken over by the src/ckeditor.js file.

Prior to v11.0.0 both files existed at the same time. The src/ckeditor.js file was automatically created from build-config.js by the npm run build command. Then, src/ckeditor.js was passed via webpack to produce build/ckeditor.js. This meant that the configuration of a build was duplicated.

Right now, your build's configuration is kept in one place — src/ckeditor.js. This file is a proper JavaScript module so it's also more flexible than the declarative build-config.js.

The Updating build configuration section describes modifying this file. You can also find more examples in Installing plugins.

npm run build's job is to call webpack --production

Previously the npm run build script had to produce src/ckeditor.js file and then call webpack. Right now, its job is trivial: it calls webpack --production.

Upgrade to webpack 4

Besides changing the structure of build source repositories, we also decided to finally migrate to webpack 4. webpack 4 was released in February, however, it brought a good number of breaking changes so we decided to stick to webpack 3 until this situation stabilizes.

The situation clarified recently so we decided to make the move in v11.0.0. This required releasing new versions of @ckeditor/ckeditor5-dev-utils and @ckeditor/ckeditor5-dev-webpack-plugin as well as updating the existing webpack.config.js files.

If, previously, you didn't have to change webpack's configuration, then it means that you won't need to do that now either. However, please note that:

• The devDependencies section of a build's package.json changed significantly. Nearly all packages had major releases, some were removed and some added. You can check all the changes in this diff. Make sure to rm -rf node_modules/ && npm i.
• Regarding webpack.config.js itself. From the most important changes we replaced babel-minify-webpack-plugin with the the uglifyjs-webpack-plugin plugin which is the default choice of webpack 4 . ModuleConcatenationPlugin() became part of the official production mode so we could remove it. You can check the diff.

src/ckeditor.js changed, too

We noticed that those of you who chose to modify that file instead of build-config.js had problems with the structure of the Editor.build property. We decided to split it into two separate properties: Editor.builtinPlugins and Editor.defaultConfig.

You can check what it meant to src/ckeditor.js in this diff.

Summary

We squeezed all these changes in one CKEditor 5 release because we hope that it will be easier for you to make the upgrade once. We believe that these changes were worth the effort and made builds easier to understand and maintain.

Upgrading CKEditor 5 installed from source

If you integrated CKEditor 5 from source into your application and want to upgrade CKEditor 5 to version 11.0.0 it's recommended that you upgrade webpack to version 4. The latest release of CKEditor 5 was built with this version of webpack. Building it with webpack 3 should still be possible, but upgrading to webpack 4 will be safer.

webpack 4 was released in February, however, it brought a good number of breaking changes so we decided to stick to webpack 3 until this situation stabilizes.

The situation clarified recently so we decided to make the move in v11.0.0. This required releasing new versions of @ckeditor/ckeditor5-dev-utils and @ckeditor/ckeditor5-dev-webpack-plugin as well as updating the existing webpack.config.js files.

We will update this guide with a description of changes that you may need to do to upgrade to webpack 4 soon. For now, please check out how webpack.config.js changed in one of the builds and how the dependencies changed.

[Reinmar]

I updated the first message with a first draft of the migration guide. It's not complete yet. I'll work on it tomorrow.

[Reinmar]

OK, I think we can close this ticket by now.