🦸 Improving CKEditor 5 installation methods

[Witoso]

Imagine you are setting up this cool editor for your app. You copied snippets from the docs, installed the packages, and quickly embedded the editor in your app. Everything works, you can type, and play with it. But now you start thinking about your specific use case. There’s just this one plugin that you want to add. You do it… and all hell breaks loose 🔥🔥🔥 Wall of errors, misleading docs. “I copied it straight from the docs! What’s wrong?! 😖 ” bangs in your head.

This is just one scenario of misleading onboarding to CKEditor 5. Which, you ask? The one where you extend a predefined build with additional plugins. 😮‍💨

Over the years, we learned a lot about the issues that you are facing. We resolved some and worked around some others, but the core issues remained there. We feel that it's now the right time to get to the root of it. 💪

For the past few months, we have researched the topic even further, focusing on these key issues:

• We have several methods of installation. Each has its specific quirks that make using the documentation difficult.
• The source packages that we release to npm need a specific setup, like webpack scripts, or a Vite plugin.
• Certain popular environments require various workarounds to set up CKEditor 5 (e.g. server-side rendered (SSR) applications like Next.js, Nuxt.js, or SvelteKit).

The ultimate goal is to make setting up of CKEditor a pleasure, not a nightmare. It should feel like adding another library to your application — nothing more, nothing less. And we came up with a plan for how to do that.

Now, we need your help!

Share your experiences, ask us questions, correct our assumptions, and show your unique use cases. Finally, let us know if you like the proposed direction. 🙏

The RFC with the details is in the first comment below. Join us on this exciting ride!🎢

[filipsobol]

As we explained in the first comment, our current setup methods are not optimal. In this RFC, we will dive deeper and expand on our thought process and proposal.

Problems 😓

WYSIWYG editors are one of the most complex frontend projects and this affects current CKEditor 5 installation methods. Moreover, we have added some complexity due to the lack of standardization in the JavaScript ecosystem when we created this project, browser limitations, and most importantly, technical debt.

We feel it is time to remove some of that complexity.

The build step

Currently, the editor code requires a special build step to resolve non-standard CSS and SVG imports and to automatically add required theme styles and translations. Also, the editor itself does not allow dynamic plugin registration.

The consequence of these two technical limitations is that we ended up with multiple distribution options, each serving a different need:

1. Distribution of pre-built editors with a fixed set of plugins, but without the ability for you to add more of them.
2. Distribution of complete webpack and Vite setups with CKEditor-specific plugins needed to build the editor that allow you to select the plugins you need and remove everything else from the bundle.
3. Distribution of DLLs that are pre-built and give you full control over what is included, but depend on the webpack-specific plugin and logic.

In other words, you either have control over the editor bundle or the developer tools you use. This is certainly not typical for a modern library, as you should have control over both.

Deviation from standards and best practices

There are a few areas where we deviate from standards and best practices:

• Although we use the ESM system, our packages are not shipped as valid ESM packages. This causes problems in Vite.
• Our code contains side effects and calls browser-specific globals even before the .create() method is called. This causes issues in server-side rendered applications.
• The JavaScript bundles include inlined CSS. You get everything in one import, but:
  • They cause errors in server-side rendered applications because there is no global document object needed to inject the CSS into the DOM.
  • They make it difficult to style the editor, which is limited to using CSS variables.
  • They impact performance by forcing browsers to do extra work compared to using plain CSS.
  • They prevent parallelization of downloads.
• Icons can only be changed using the webpack plugin.
• Translations use the global object. You do not have to register them in the editor configuration, but:
  • They cause errors in server-side rendered applications because there is no access to the global window object.
  • They cause side effects.
  • They pollute the global scope.

Note

We do not plan to support server-side rendering of CKEditor 5 itself. We only want to fix errors thrown by the CKEditor code when other applications render on the server side.

Minor annoyances

There are other smaller issues, like:

• The ckeditor-duplicated-modules error caused by mistakenly installing plugins in different versions.
• Difficulty creating universal copy-and-paste code snippets in the documentation that would cover all possible setups.

Goals 🎯

Once we identified the problems, we started looking at how the latest standards and best practices could help us solve them. This also included researching how other popular and modern JavaScript libraries are built and shipped, and what are some of the pain points for their authors and users. This helped us define our goals.

Improve the developer experience

Developer experience is difficult to measure, but you know when a library is doing it right. We currently lack good developer experience when it comes to the editor setup, but we feel like we know what the right direction is to significantly improve it:

• Be more explicit and avoid magic and side effects. Nothing should happen without the developer's knowledge because things that happen magically are confusing.
• Adhere to standards because they are a safer bet than custom solutions. They can help avoid unexpected problems with new tools introduced in the future. Standards are also well known to most developers.
• Distribute ready-to-use code that does not require custom processing, runs directly in the browser, and works the same regardless of the setup (npm or CDN).

Stick with the standards

CKEditor should stand out for its great and unique features, not for its funky installation methods. With this in mind:

• The distributed JavaScript should:
  • Be distributed as a valid ESM.
  • Be standard JavaScript that does not require CKEditor-specific plugins, so it runs in any project and works with any bundler.
  • Not contain SVG imports, but have them converted to strings.
  • Have no side effects, nor access any browser-specific globals (like document or window) before the .create() method is called to avoid problems when using the editor in server-side rendered applications.
• The distributed CSS should be:
  • Standard CSS that does not require processing with PostCSS.
  • Distributed separately from JavaScript to allow parallel downloading and easy overriding.
• The SVG icons should be easy to change using the editor configuration.
• The translations should not create a global object and pollute the scope. They should be passed to the editor configuration.
• The ckeditor5 package should act as a central point for developers and export everything from all open-source packages to:
  • Reduce the number of dependencies that need to be synchronized to avoid the ckeditor-duplicated-modules error.
  • Eliminate the need to install new packages when extending the editor with new plugins.
  • Hide implementation details and a huge package ecosystem.
  • Aggregate CSS and translations to avoid having to install them separately for each plugin.
  • Improve the CDN loading performance, as one large download is faster than many smaller ones, even when using HTTP/2.

Future 🚀

The goals described above will allow us to reduce the number of installation methods to just two: npm and CDN. This is what the CKEditor setup will likely look like in both methods after the changes.

npm setup

Below is the minimal setup you will need to create the editor in a regular JavaScript or TypeScript project. There are a few things to note about this example:

• All plugins are imported from the ckeditor5 package.
• Translations are explicitly added to the editor configuration object.
• Styles are separated from the JavaScript bundle and explicitly imported.
• No special setup is required. You can run this code in any frontend metaframework or build it with any bundler without any CKEditor-specific plugins.

import { ClassicEditor, Essentials, Paragraph } from 'ckeditor5';
import translations from 'ckeditor5/translations/pl.js';

import 'ckeditor5/styles.css';

await ClassicEditor.create( document.querySelector( '#editor' ), {
  plugins: [
    Essentials,
    Paragraph,
  ],
  toolbar: {
    items: [ 'undo', 'redo' ]
  },
  translations
} );

CDN setup

Below is the same setup using the CDN solution. Same as above, in this setup:

• All plugins are imported from a single URL.
• Translations are explicitly added to the editor configuration object.
• Styles are separated from the JavaScript bundle and added explicitly.

This setup uses importmaps. This allows you to use the same import paths inside the <script> tag as in the npm setup.

<link rel="stylesheet" href="<CDN_LINK>/ckeditor5/dist/styles.css">

<script type="importmap">
{
  "imports": {
    "ckeditor5": "<CDN_LINK>/ckeditor5/dist/index.min.js",
    "ckeditor5/": "<CDN_LINK>/ckeditor5/dist/"
  }
}
</script>
<script type="module">
import { ClassicEditor, Essentials, Paragraph } from 'ckeditor5';
import translations from 'ckeditor5/translations/pl.js';

await ClassicEditor.create( document.querySelector( '#editor' ), {
  plugins: [
    Essentials,
    Paragraph,
  ],
  toolbar: {
    items: [ 'undo', 'redo' ]
  },
  translations
} );
</script>

Easier icons overriding

To simplify overriding the editor icons, we will introduce a new icons configuration option. It takes an object where the key is the icon identifier and the value is the stringified SVG.

await ClassicEditor.create( document.querySelector( '#editor' ), {
  // Other options
+  icons: {
+    bold: '<svg viewBox="0 0 20 20" xmlns="http://www.w3.org/2000/svg">...</svg>'
+  }
} );

No more CKEditor-specific setups

Once the code we distribute no longer requires custom processors, you can remove CKEditor-specific plugins from your webpack or Vite setup. If you already have a JavaScript or TypeScript project, you can remove the dedicated CKEditor setup and import the editor directly inside your project.

Vite

-import { createRequire } from 'node:module';
-const require = createRequire( import.meta.url );

import { defineConfig } from 'vite';
-import ckeditor5 from '@ckeditor/vite-plugin-ckeditor5';

export default defineConfig( {
    plugins: [
-        ckeditor5( { theme: require.resolve( '@ckeditor/ckeditor5-theme-lark' ) } )
    ]
} );

webpack

- const { bundler, styles } = require( '@ckeditor/ckeditor5-dev-utils' );
- const { CKEditorTranslationsPlugin } = require( '@ckeditor/ckeditor5-dev-translations' );

module.exports = {
  // Some configuration options are skipped for readability.

  plugins: [
-    new CKEditorTranslationsPlugin( {
-      language: 'en',
-      additionalLanguages: 'all'
-    } ),
-    new webpack.BannerPlugin( {
-      banner: bundler.getLicenseBanner(),
-      raw: true
-    } )
  ],

  module: {
    rules: [
      {
        test: /\.css$/,
        use: [
-          {
-            loader: 'postcss-loader',
-            options: {
-              postcssOptions: styles.getPostCssConfig( {
-                themeImporter: {
-                  themePath: require.resolve( '@ckeditor/ckeditor5-theme-lark' )
-                },
-                minify: true
-              } )
-            }
-          }
        ]
      }
    ]
  }
};

Fewer dependencies

Because the ckeditor5 package contains all open-source packages, you can remove all other packages from your dependencies. We will also distribute a similar package for our commercial plugins.

"dependencies": {
-  "@ckeditor/ckeditor5-editor-classic": "42.0.0",
-  "@ckeditor/ckeditor5-essentials": "42.0.0",
-  "@ckeditor/ckeditor5-highlight": "42.0.0",
-  "@ckeditor/ckeditor5-list": "42.0.0",
-  "@ckeditor/ckeditor5-paragraph": "42.0.0",
-  "@ckeditor/ckeditor5-table": "42.0.0",
-  "@ckeditor/ckeditor5-theme-lark": "42.0.0",
   "ckeditor5": "42.0.0"
}

DLLs and predefined builds

Until now, predefined builds and DLLs were a good choice for those who wanted to avoid the build step. The main difference between them is that predefined builds do not give you any control over the included plugins, while DLLs do.

Since the new setup methods no longer require a build step while still giving you full control over the plugins used, there will be no need to use predefined builds and DLLs. We plan to slowly deprecate them.

You can find more details in the RFC dedicated to DLLs.

Initial delivery plan

At the time of writing this RFC, we have already passed the proof-of-concept stage with promising results. We have also begun the process of rewriting and restructuring our documentation.

Unfortunately, we have found that it is not possible to introduce new setup methods without introducing some breaking changes. We have tried to minimize the impact on existing projects by phasing them in so that the effort required does not block or discourage you from upgrading.

This project is expected to be delivered in the first and second quarters of 2024.

Phase 1. Foundation

In the first phase, we will introduce breaking changes necessary to ship the new installation methods. These changes will allow us to continue supporting projects created using the old methods. In it, we will:

• Upgrade TypeScript to v5.0 #15452
• Resolve exports conflicts in ckeditor5 package. #15511
• Make CKEditor 5 packages valid ESM #13673

There may be other breaking changes in this release unrelated to this RFC.

Phase 2. Release

In second phase we will introduce the new setup methods. They will be opt-in and the old ones will continue to work, but we are still discussing for how long. However, from then on, we will start promoting the new methods as defaults. We will also work with package authors to help them migrate their plugins.

Breaking changes in this release only apply to projects that upgrade to the new setup methods.

In this release, we will:

• Export the editor core and all open-source packages from the ckeditor5 package.
• Extract styles from JavaScript bundles into separate CSS files.
• Change the way translations are generated. They will need to be passed to the editor configuration instead of relying on the global object.
• Allow overriding icons using the editor configuration.

Phase 3. Elevation

In the last phase, we will continue to improve the developer experience by addressing issues with using the editor in server-side rendered applications, improving error handling, and potentially upgrading released code to ES2022 to improve performance and readability.

"In the meantime"

We are also very excited about a companion project that will simplify the installation and setup process even more. It will remain a secret for now 🤫.

Probable migration paths 🛣️

Your migration path will depend on your current setup and whether you use the CDN or npm as the new method. In the migration paths described below, we have made assumptions about which version you are more likely to use.

The migration paths may change slightly before the final release.

CDN

Currently, our CDN only distributes predefined builds with a known list of plugins. After the changes, we will distribute the ckeditor5 package containing all the open-source plugins, so you have full control over which ones you use, as well as loaded styles, and translations.

Predefined builds have a known set of plugins, so with the release, we will provide code you can copy and paste in place of the old setup. There will thus be no extra work on your end.

Some of you may wonder how bundling all the packages together will affect the size of the distributed file. The good news is that it will not change much. The predefined builds already include the editor's core and the heaviest plugins. We estimate that the new approach will increase the download size by about 20%, although the exact number is not yet known. However, we are considering a way to generate a personalized CDN URL with only the code you need and everything else removed.

Predefined builds

As with the CDN, the predefined builds have a known list of plugins, so with the release, we will provide code you can copy and paste in place of the old setup. There will thus be no extra work on your end.

However, if you are using a frontend metaframework (like Next.js, Nuxt, SvelteKit) or bundler (like webpack, Rollup, Vite), then unlike the CDN, it should remove all unused code, likely resulting in a smaller bundle compared to the current predefined builds.

Customized builds / integrating from source / online builder

Custom builds no longer require a separate webpack or Vite setup. If you want to continue using them, you can. The CKEditor-specific plugins will no longer be needed.

However, if you would like to remove this setup, and you are already using a frontend metaframework (like Next.js, Nuxt, SvelteKit) or bundler (like webpack, Rollup, Vite), you can import the CKEditor code directly into your project.

When it comes to the editor code, you will need to:

• Remove all CKEditor dependencies except for the ckeditor5 package.
• Import all plugins from ckeditor5 instead of individual packages.
• Add the CSS import.

We will provide code examples to help you migrate, but the exact configuration will depend on the plugins you use.

DLLs

The most notable difference between the new installation methods and DLLs is that the new approach will not expose the CKEditor5 global object.

Other than that, as shown in the "Future" section, you will also need to:

• Import plugin and editor classes from the ckeditor5 package instead of relying on the CKEditor5 global object.
• Add the CSS import.

We will provide code examples to help you migrate, but the exact configuration will depend on the plugins you use.

You can find more details in the RFC dedicated to DLLs.

Plugin authors

For those of you using the package generator to create custom plugins, we will introduce a new command that will build the package for the new format. The command will output a dist folder containing a JavaScript bundle, and optionally a separate CSS and global-free translation files.

You will need to decide if you want to support both the old and new setup methods or just the new one. Based on this, the old setup may still work, but the setup method for the new build will be similar to what we showed in the "Future" section, and will require you to:

• Register a plugin itself (no change here).
• Import CSS styles if your plugin has custom styles.
• Add translations to the editor configuration if your plugin includes them.

+ import { MyPlugin } from '<path_to_plugin>';
+ import MyTranslations from '<path_to_plugin>/translations/<lang_code>.js';

+import '<path_to_plugin>/styles.css';

await ClassicEditor.create( document.querySelector( '#editor' ), {
  plugins: [
    MyPlugin
  ],
  translations: [
+    MyTranslations,
    // Other translations.
  ]
} );
</script>

Feedback 💬

We've done our best to thoroughly examine the existing problems, consider dozens of integration scenarios that we know of, research how other libraries and components have approached the problems, and finally how we can apply the modern standards to our specific needs. However, we may have missed something, and that is where we need your feedback.

Let us know if you like the proposed changes, if you have questions or doubts, or just react with 👍 or 👎 below the RFC so we know if we are on the right track.

We'll adjust the RFC in response to your comments or as the project evolves. To keep everyone up to date, we will add a new comment below whenever we make changes.

[filipsobol]

We understand that theory can make some concepts difficult to understand, and some of you may want to try out the new installation methods right away. That's why we've prepared a small demo that shows how the new installation method works with Vite and Webpack, but you can also run it in your setup. For more information, check out this repository, but please note that this demo is limited and by no means production-ready.

[Witoso]

Happy to tag, and invite users that over past years contributed to the development through issues, comments, and feedback: @huzedong2015 @mmichaelis @dtdesign @slotterbackW @lauriii @wimleers @star-szr @Inviz @Kocal @urbanspr1nter

[Kocal]

Hi 👋🏻

I skimmed through all of this and saw some interesting things, I'll read better later after work :)

[dtdesign]

I really appreciate the vast amount of thoughts you put into this to address some existing pain points. 👍

The icons are a real pain point because it is common for sites to use an existing icon set and although I do like most of the editor icons, sometimes it makes more sense to swap them out for a unified appearance. Replacing icons with a HTML string is a great idea because it is dead simple and flexible at the same time, for example we use a custom web component <fa-icon> to embed icons.

I’m also glad to see that you are taking steps to extract the CSS from the bundle. During a public beta test I did notice that the style tags caused a significant slow-down because it would trigger style calculations plus having to start the browser’s CSS parser a bazillion times isn’t cheap. However, that is already possible today with the MiniCssExtractPlugin that exports the CSS into a single file: https://github.com/WoltLab/editor/blob/4890e96907757b66c2ea29dfdb4f92fc6692d79d/webpack.config.js (LGPL v2.1, feel free to steal).

While you are at it, I also added the postcss-hover-media-feature to the built step to put all :hover selectors behind @media (hover: hover). It is very well supported in both recent and somewhat dated browsers and it prevents all those hover effects from being a sticky pain on touch devices. It’s not exactly an issue with the installation method, but it sort of overlaps with the limited CSS customization options.

Lastly, the plugins are a real issue for us. Our software is designed to run on plain web hosting accounts without access to a shell or similar. That means that the customer on average has no means to compile the bundle on their own, so whatever plugins we ship are set in stone. We solved this issue by exposing the bundled classes through a custom export so that plugins for our software can dynamically define plugins for the editor by relying on all the exported classes. It’s a bit ugly but it works, however, I don’t know if this can be solved in a better way with webpack.

[Inviz]

Looking forward for this to evolve into headless builds at some point. Ability to build without any ui plugins would be greatly appreciated.

[quicksketch]

This proposal gives me a lot of concern. The transition from CKE4 to 5 has already been extraordinarily painful. Now that CKE4 is EOL, most projects depending on CKE have made the jump. What I'm reading here is that now after finally figuring out CKE5, pretty much every plugin that extends CKE5 is going to need a substantial effort to keep working (probably forking for pre and post this change). It will depend on the migration tools/methods available, but at first blush this proposal sounds like it puts too much emphasis on a shiny, better future without enough regard to the existing projects that will be substantially disrupted.

From what I've seen in the CMS-world, the DLL builds are the only realistic compilation option currently, since any CMS with their own module/plugin system need to be able to enable CKEditor plugins without recompiling the main bundle. I'm not sure if it's implied in the RFC, but an additional goal should be:

• Plugins can be distributed and loaded separately from the main compiled bundle, across directories and domains.

Plain vanilla JS plugins should be possible to be loaded without any compilation at all. If the CKEditor5 global is eliminated I'm concerned that won't be possible.

[urbanspr1nter]

Happy to tag, and invite users that over past years contributed to the development through issues, comments, and feedback: @huzedong2015 @mmichaelis @dtdesign @slotterbackW @lauriii @wimleers @star-szr @Inviz @Kocal @urbanspr1nter

Thanks @Witoso - Will take a look at the end of week/weekend.

[Kocal]

Hi again :)

I'm really happy for the CKEditor-specific setups removal, I know you did what you could, but building CKEditor 5 from source is a really big mess, specially if you want an optimized CSS file, and it's slow, surely due to the use of webpack?

Anyway, all this good news will allow me to lighten my configuration file like this 😄 :

const path = require('path');
const webpack = require('webpack');
-const { CKEditorTranslationsPlugin } = require('@ckeditor/ckeditor5-dev-translations');
-const { styles } = require('@ckeditor/ckeditor5-dev-utils');
const MiniCssExtractPlugin = require('mini-css-extract-plugin');
-const postCssContentStylesPlugin = require('./build/postcss/list-content-styles-plugin');
-const { CKEditorContentStylesPlugin } = require('./build/webpack/CKEditorContentStylesPlugin');
-const { CKEditorMinifyStylesPlugin } = require('./build/webpack/CKEditorMinifyStylesPlugin');

-/**
- * Custom Webpack configuration for CKEditor 5, as we want to keep it isolated from the rest of the application/toolchain.
- * It also extracts the content styles from the built editor CSS files, to a "content styles" CSS file.
- *
- * @see https://ckeditor.com/docs/ckeditor5/latest/installation/advanced/alternative-setups/integrating-from-source-webpack.html
- * @see https://github.com/ckeditor/ckeditor5/blob/master/scripts/docs/build-content-styles.js
- */

-const contentRules = {
-    selector: [],
-    variables: [],
-    atRules: {},
-};

-const postCssConfig = styles.getPostCssConfig({
-    themeImporter: {
-        themePath: require.resolve('@ckeditor/ckeditor5-theme-lark'),
-    },
-    minify: false,
-});
-postCssConfig.plugins.push(postCssContentStylesPlugin(contentRules));

module.exports = {
    entry: {
        'editors/default': './src/editors/default.ts',
        'editors/admin': './src/editors/admin.ts',
        'editors/front_forum': './src/editors/front_forum.ts',
        'editors/front_forum_admin': './src/editors/front_forum_admin.ts',
    },
    output: {
        path: path.resolve(__dirname, 'dist'),
        filename: '[name].js',
        library: {
            name: '[name]',
            type: 'umd',
        },
        clean: true,
    },
    devtool: false,
    resolve: {
        extensions: ['.tsx', '.ts', '.js'],
    },
    module: {
        rules: [
            {
                test: /.([cm]?ts|tsx)$/,
                loader: 'ts-loader',
            },
            {
                test: /ckeditor5-[^/\\]+[/\\]theme[/\\]icons[/\\][^/\\]+\.svg$/,
                type: 'asset/source',
            },
            {
                test: /ckeditor5-[^/\\]+[/\\]theme[/\\].+\.css$/,
                use: [
                    MiniCssExtractPlugin.loader,
                    'css-loader',
                    {
                        loader: 'postcss-loader',
                        options: {
                            postcssOptions: {
-                                ...postCssConfig,
                                config: false,
                            },
                        },
                    },
                ],
            },
        ],
    },
    plugins: [
-        new CKEditorTranslationsPlugin({
-            // See https://ckeditor.com/docs/ckeditor5/latest/features/ui-language.html
-            language: 'fr',
-            additionalLanguages: ['en', 'de', 'it', 'es', 'pl', 'nl'],
-            buildAllTranslationsToSeparateFiles: true,
-            packageNamesPattern: /([/\\]ckeditor5-[^/\\]+[/\\])|(src\/plugins\/[^/\\]+)/,
-            sourceFilesPattern: /([/\\]ckeditor5-[^/\\]+[/\\]src)|(src\/plugins\/[^/\\]+)[/\\].+\.[jt]s$/,
-        }),
        new MiniCssExtractPlugin({
            filename: '[name].css',
        }),
        // https://github.com/TypeStrong/ts-loader#usage-with-webpack-watch
        new webpack.WatchIgnorePlugin({
            paths: [/\.js$/, /\.d\.[cm]ts$/, /\.txt$/],
        }),
-        new CKEditorContentStylesPlugin({
-            contentRules,
-        }),
-        new CKEditorMinifyStylesPlugin(),
    ],
};

However, I have a have one concern about how translations will be loaded.

In our CMS app, we have many languages and therefore as many CKEditor translations .js files. We don't load every translations at once, but only the needed one, through a dynamic import:

async function loadEditor({ editor, language }) {
    import(`../build/ckeditor/dist/translations/${language}.js`);

    // editor loading ...
}

Do you think this would be possible with the proposed solutions?
Could translations accepts a Promise? Or should I wait my translation to be loaded before creating the Editor like this? :

async function loadEditor({ editor, language }) {
    const translations = await Promise.all([
        // `build/ckeditor` is a directory dedicated to build CKEditor
        import(`../build/ckeditor/dist/translations/${language}.js`),
        
        // and what about plugins's translations?
   ]);

    return await ClassicEditor.create('...', {
        translations,   
    });
}

Thanks! :)

[Witoso]

Thanks for the comments so far 🙏, we will craft a lengthier response a bit later, and probably add details to the RFC body.

@quicksketch, thanks for the remarks! We know that DLLs are used in Drupal ecosystems, and other CMS platforms, and our clients use them as well. We haven't decided on the moment of the DLLs deprecation, but we are preparing for a long time of supporting them.

Plain vanilla JS plugins should be possible to be loaded without any compilation at all. If the CKEditor5 global is eliminated I'm concerned that won't be possible.

This is our goal as well, the new method will not be a blocker here, details will follow :)

[quicksketch]

Thanks @Witoso. That's a big relief. I'm not a JS expert, but this statement is what had me worried:

Import plugin and editor classes from the ckeditor5 package instead of relying on the CKEditor5 global object.

AFAIK, import statements require a path structure. The DLL approach has allowed plugins to extend CKEditor without knowing anything about where other libraries are located. I'll hold my concerns until there is further clarification.

[urbanspr1nter]

@Witoso @filipsobol

Really good stuff! I think most of these are good proposals, and coincidentally, addresses a lot of the pain points I've had in the past! 😁

Overall summary of what I would appreciate seeing:

1. Option to not include UI components when importing packages. Right now whenever we consume a plugin, we not only get the Editing but also the UI classes within the plugin. Is there some way to avoid this? For instance, hard to take advantage of a potential smaller bundle size as we cannot shake this off on import.
2. Embedding SVG icons and CSS into the build is unnecessary - I really appreciate seeing the recognition in this concern. Again, another win on loading perf for integrators who need to have a small bundle size.
3. Most importantly, I would like to see documentation which directly reflects how we should really build from source. I've been successful at this in the past, but there are some gotchas that I keep forgetting to help with updating the documentation with.

As you can probably notice, my main concern has always been the bundling of some of the UI elements as opposed to the process in creating the build, but off the top of my head:

I would like to have some clear way to avoid the dreaded duplicated-modules error. For us, we have a strange way of building the source, but it makes it hard to pull down other handy classes and utils and utilize (impossible really)

[filipsobol]

@dtdesign

While you are at it, I also added the postcss-hover-media-feature to the built step to put all :hover selectors behind @media (hover: hover). It is very well supported
in both recent and somewhat dated browsers and it prevents all those
hover effects from being a sticky pain on touch devices.

Thank you, we will investigate how @media (hover: hover) can improve the mobile experience.

Lastly, the plugins are a real issue for us. Our software is designed to
run on plain web hosting accounts without access to a shell or similar.
That means that the customer on average has no means to compile the
bundle on their own, so whatever plugins we ship are set in stone. We
solved this issue by exposing the bundled classes through a custom export
so that plugins for our software can dynamically define plugins for the
editor by relying on all the exported classes. It’s a bit ugly but it
works, however, I don’t know if this can be solved in a better way with
webpack.

Although we will be encouraging the use of the ckeditor5 package, you can still import from individual plugins. When you're ready to migrate to the new installation method, you'll need to append all imports with /dist/index.js (e.g. @ckeditor/ckeditor5-alignment/dist/index.js) and import CSS styles and translations as shown in the RFC. This is a good way if you want to migrate, but also want to minimize changes in your project.

However, our new CDN build may be ideal for your use case because it does not require compiling or bundling. As shown in the RFC, you'll be able to access all plugins and the editor core from one file thanks to importmaps. This means that unless you need to use TypeScript, you can skip the build step for custom plugins and run them directly in the browser. I've updated our demo repository to show this in action. In the new "browser demo", we create an editor with the most basic plugins and register a custom plugin that runs directly in the browser without any processing.

If you need to process your source code (e.g. because you're using TypeScript), we’ll provide the tools necessary to create CDN builds for custom plugins.

[filipsobol]

@Kocal

Reducing the length of the webpack config is always nice, isn't it? 🙂

In our CMS app, we have many languages and therefore as many CKEditor translations .js files. We don't load every translations at once, but only the needed one, through a dynamic import:
[…]
Do you think this would be possible with the proposed solutions?

Dynamic import should work just the same.

Could translations accepts a Promise? Or should I wait my translation to be loaded before creating the Editor like this?

We’ll discuss this internally, but it's much more likely that you'll need to resolve the promise before creating the editor.

[filipsobol]

@urbanspr1nter

Option to not include UI components when importing packages. Right now whenever we consume a plugin, we not only get the Editing but also the UI classes within the plugin. Is there some way to avoid this? For instance, hard to take advantage of a potential smaller bundle size as we cannot shake this off on import.

It's not in the scope of this initiative, but we're aware of that limitation because it comes back like a boomerang. It’s possible it will be a follow-up after we clean up the installation methods. (cc: @Inviz)

Embedding SVG icons and CSS into the build is unnecessary - I really appreciate seeing the recognition in this concern. Again, another win on loading perf for integrators who need to have a small bundle size.

Unfortunately, SVG icons will still be part of the bundle (as inlined strings). We have looked into making them optional, but that would require introducing a breaking change to the existing installation methods, which we do not want to do, as the changes we are introducing are already major.
They may become optional in the future, but this will likely not happen as part of this initiative.

Most importantly, I would like to see documentation which directly reflects how we should really build from source. I've been successful at this in the past, but there are some gotchas that I keep forgetting to help with updating the documentation with.

We are in the process of restructuring and reworking all of our setup and installation documentation. I can already say that it will be much better.

I would like to have some clear way to avoid the dreaded duplicated-modules
error. For us, we have a strange way of building the source, but it
makes it hard to pull down other handy classes and utils and utilize
(impossible really)

With the ckeditor5 package containing everything, the duplicated-modules error will largely disappear, as you'll have one central entry point and one direct dependency instead of dozens of interdependent packages.

[filipsobol]

@quicksketch

Thank you for sharing your concerns. We do our best to ensure that the changes we introduce are not disruptive to the CMS platforms and that you have reasonable migration paths.
From the beginning, we knew that because of the way DLLs work and the number of projects that depend on them, they needed to be treated differently than other installation methods. As a result, DLLs will have a longer deprecation window than other installation methods.
In addition, after discussing your concerns internally, we have decided to prepare an additional RFC specific to DLLs that will discuss our reasons for deprecating them, likely migration paths, and timelines. We will also use it to better understand how they are used by projects like yours.

What I'm reading here is that now after finally figuring out CKE5, pretty much every plugin that extends CKE5 is going to need a substantial effort to keep working (probably forking for pre and post this change).

The DLLs and the new package bundles can be generated from the same source code, so there's no need to make forks. We will add a new command to the Package generator to generate the new bundles, and the old commands will continue to work. It will be up to package developers to decide if they want to support only the new method or both. To ensure better interoperability, we’ll recommend releasing both.

From what I've seen in the CMS-world, the DLL builds are the only realistic compilation option currently, since any CMS with their own module/plugin system need to be able to enable CKEditor plugins without recompiling the main bundle.
[..]
Plain vanilla JS plugins should be possible to be loaded without any compilation at all. If the CKEditor5 global is eliminated I'm concerned that won't be possible.

Our new package bundles don’t require compilation or bundling. They also allow creating custom plugins that can be developed and used without bundling/compilation. I've updated our demo repository to show this in action. In the new "browser demo", we create an editor with the most basic plugins and register a custom plugin that runs directly in the browser without any processing.
All of this is possible without global CKEditor5 object.

[quicksketch]

I've updated our demo repository to show this in action. In the new "browser demo", we create an editor with the most basic plugins and register a custom plugin that runs directly in the browser without any processing.
All of this is possible without global CKEditor5 object.

Thanks @filipsobol. The concept of browser importmaps is new to me but using the example repository it demonstrated clearly to me how imports can be done without using path structures within the plugin files. That would allow loading plugins across domains and directories as I was hoping for, and without compilation for the individual plugins.

In addition, after discussing your concerns internally, we have decided to prepare an additional RFC specific to DLLs that will discuss our reasons for deprecating them, likely migration paths, and timelines.

Perfect, thank you very much. The deprecation of DLLs as part of the 40.2.0 release notes without a clear replacement was alarming.

Overall, I think this new approach is much better, and it would be nice to not need special DLL distribution files. I still see the transition to be bumpy, but I'm relieved to see my primary concerns are already addressed.

[filipsobol]

We have some exciting news to share about the progress of the new installation methods project.

After about 370 commits and weeks of testing, we are adding the new installation methods to our nightly releases. This marks the beginning of the beta phase of the project. The new builds have no known bugs and are ready for testing. You can check out the updated demo repository for examples of using the new installation methods with Vite, webpack, React or directly in the browser.

In the coming days we'll be updating our Package Generator for those of you who maintain custom CKEditor 5 plugins. This update will include our newly created tool that allows you to build CKEditor integrations for the new installation methods from source code that still uses the old installation methods. This is the same tool we use to build CKEditor 5 itself, and it's only needed for those who want to support both installation methods during the transition period (until the old installation methods are fully deprecated). Those of you who maintain custom plugins and want to switch to the new installation methods all at once do not need it. In fact, you will probably no longer need the package generator anymore and can use any bundler you want or even skip the build step altogether.

The new installation methods are not yet ready for production, but we are getting there. While there are no known issues with the new builds, we are still working on tree shaking improvements and a major overhaul of the documentation.

We expect to reach the release candidate stage in a few short weeks, where we will focus on the final touches and documentation. We will also be working on the migration guides to help you transition from the old installation methods to the new ones.

To help us get there, we encourage you to try the new installation methods and report any problems you encounter. We are aware that the demo repository doesn't cover all possible scenarios, so if you're not sure how to test new builds with your specific setup, please let us know.

[DeltekDavid]

We are currently blocked trying to integrate CKEditor5 into a project that uses react-app-rewired. Ejecting isn't really an option for us. We get an error like

Failed to compile.

./node_modules/@ckeditor/ckeditor5-ui/theme/components/colorselector/colorselector.css (./node_modules/css-loader/dist/cjs.js??ref--6-oneOf-3-1!./node_modules/postcss-loader/src??postcss!./node_modules/@ckeditor/ckeditor5-ui/theme/components/colorselector/colorselector.css)
Module not found: Can't resolve './@ckeditor/ckeditor5-ui/theme/mixins/_dir.css' in 'C:\Repos\ourApp\node_modules\@ckeditor\ckeditor5-ui\theme\components\colorselector'

I feel like we need the right config to solve this but can't find any resources. Would these new installation methods help us work around this? Any guidance available?

Thanks :) It's frustrating because we're so close to having this component work for us. Our standalone POC worked great, but now we need to integrate. Held up at the ten-yard line...

[Witoso]

I feel like we need the right config to solve this but can't find any resources. Would these new installation methods help us work around this? Any guidance available?

The new installation methods are not webpack-dependent, and use standard css import, so it looks like they may easily solve your issue. Our example repo has React+Vite example, and you can check your setup with the alpha version like 41.3.0-alpha.4.

[DeltekDavid]

Hi @Witoso , thank you for replying. We tried referencing the alpha version but got the same CSS error. Then I tried referencing the nightly build instead, like in the Demo repository. I then got a different error, which may be related to our old NodeJS version (12.22.12):

Failed to compile.

./node_modules/@ckeditor/ckeditor5-adapter-ckfinder/dist/index.js
SyntaxError: C:\Repos\specpoint_ae_client\node_modules\@ckeditor\ckeditor5-adapter-ckfinder\dist\index.js: Missing class properties transform.
   96 |     /**
   97 |          * FileLoader instance to use during the upload.
>  98 |          */ loader;
      |      ^^^^^^^
   99 |     /**
  100 |          * Upload URL.
  101 |          */ url;

I'll post an update once we've updated our Node, which will hopefully be in the next few weeks.

PS--Can I create custom plug-ins using this new install strategy (which AFAICS consists of referencing the nightly build and leaving the webpack/react-app-rewired config alone? Pretty awesome if it is that easy...)

[Witoso]

Yes, the idea is that CKEditor 5 will behave as any other library, and won't be dictating how to configure your bundler setup. But still with some restrictions, for example, we will drop support for webpack 4. AFAIR we require node 18+.

[bnf]

Hey,

In light of #16360 I'd like to share the CKeditor5 installation approach used by https://github.com/TYPO3/typo3/.
TYPO3 CMS switched to browser native ES6 modules + importmaps in 2022 and therefore decided to generate a dynamic CKEditor5 build that allows to configure which CKEditor5 module-exports (plugins) shall be loaded depending on the context where the editor is used.

Every @ckeditor5/ckeditor-* package is bundled into one file that is loadable ondemand via browser native import, e.g.: await import('@ckeditor/ckeditor5-alignment').
This is achieved by bundling the respective package files into one entrypoint file via rollup and map imports via <script type="importmap">. This works well thanks to recent refactorings that mapped all exports to the main entrypoint of the CKEditor5 scoped packages.

Example:

<script type="importmap">
  {
    "imports": {
      "lodash-es": "./assets/lodash-es.js",
      "@ckeditor/ckeditor5-alignment": "./assets/@ckeditor/ckeditor5-alignment.js",
      "@ckeditor/ckeditor5-core": "./assets/@ckeditor/ckeditor5-core.js",
      "@ckeditor/ckeditor5-editor-classic": "./assets/@ckeditor/ckeditor5-editor-classic.js"
    }
  }
</script>

<script type="module">
import { ClassicEditor } from '@ckeditor/ckeditor5-editor-classic';
import { Alignment } from '@ckeditor/ckeditor5-alignment';
ClassicEditor.create(textarea, {  plugins: [ Alignment ] });
</script>

I've created an isolated example on https://github.com/bnf/ckeditor5-importmap-demo which is easier to introspect than the entire TYPO3 integration.
Example initialization: https://github.com/bnf/ckeditor5-importmap-demo/blob/main/index.js
Demo: https://bnf.github.io/ckeditor5-importmap-demo

With this infrastructure optional plugins like "font" can be loaded via configuration and the module will only be (down)loaded if actually used. See upstream documentation on how that is used by integrators:
https://docs.typo3.org/c/typo3/cms-rte-ckeditor/main/en-us/Configuration/Examples.html#config-example-fontplugin

This dynamic loading is demonstrated in https://github.com/bnf/ckeditor5-importmap-demo/blob/main/dynamic.js#L4 (demo: https://bnf.github.io/ckeditor5-importmap-demo/dynamic.html)
That means there is no pre-build bundle/config, only dynamically composed environments.

Summary

CKEditor5 scoped packages are packaged into mini-bundles that reference other CKEditor5 packages via bare module identifiers (e.g. @ckeditor/ckeditor5-core).
See https://bnf.github.io/ckeditor5-importmap-demo/assets/@ckeditor/ckeditor5-code-block.js

Obstacles

CKEditor5 scoped packages still reference and require the (new umbrella) package ckeditor5, which we actually do not (want to) ship as it is just a wrapper and would produce uneeded roundtrips in a browser-native importmap scenario:

@ckeditor/ckeditor5-code-block
  ckedito5/src/core.js  <-- unneeded roundtrip (remember we do not bundle, but let the browser resolve dependencies via `import`)
    @ckeditor/ckeditor5-core

Therefore we rewrite the imports to use @ckeditor/ckeditor5- directly: https://github.com/bnf/ckeditor5-importmap-demo/blob/23cbd34c988943eac39e3e36050a9326569a644e/rollup.config.js#L55-L56

Outlook

It would be ideal if the bundling step would be integrated upstream in order to create these sub-bunldes during release.
BTW CodeMirror v6 uses this approach and that works very well for browser native importmap usage.
See https://github.com/codemirror/state/tree/main/src which is published as a one-file-per-package bundle in https://unpkg.com/browse/@codemirror/state@6.4.1/dist/

Thanks for listening!

[filipsobol]

Thanks for sharing your feedback @bnf. I think your approach can work with New Installation Methods (NIM) with some minor modifications.

Background

Let's start with some background information.

The ckeditor5 package exposes code from all packages and plugins as a single entrypoint, but the individual packages still directly depend on each other (e.g. @ckeditor/ckeditor5-core depends on @ckeditor/ckeditor5-engine and @ckeditor/ckeditor5-utils, not on ckeditor5). This means that in NIM it's still possible to use individual packages instead of ckeditor5, but using ckeditor5 will be much more convenient for the vast majority of developers.

Furthermore, in NIM we already rewrite the imports like ckeditor5/src/core.js to @ckeditor/ckeditor5-core (during the build process, not in the source to maintain backwards compatibility).

For an example, see the nightly build of the @ckeditor/ckeditor5-table plugin here: https://cdn.jsdelivr.net/npm/@ckeditor/ckeditor5-table@nightly/dist/index.js.

Your approach

So what do you need to do to make your approach work with NIM?

First, you still need to build the packages yourself. While we provide npm, ES browser and UMD browser builds for the ckeditor5 package, we only provide npm builds for individual packages. The good news is that these packages no longer require any custom build configuration or plugins, so you are free to use any bundler (e.g. webpack, Rollup, esbuild, etc.) to bundle them however you like.

Second, to maintain backwards compatibility, the imports in NIM contain /dist/index.js (e.g. @ckeditor/ckeditor5-core/dist/index.js, @ckeditor/ckeditor5-engine/dist/index.js, etc. See the file linked above). This means that you either have to rewrite your import maps to use these paths (and also use them in your code), or you can rewrite these paths yourself during the build process (which you already do for ckeditor5/src/*) to remove /dist/index.js.

Considerations

I would like to point out that the ckeditor5 package is still the recommended way to use CKEditor 5 for most projects, and that counter-intuitively it might offer better performance, even though it contains a bunch of plugins you don't use. It of course depends on the setup, but it's generally faster to load a single large file than multiple smaller ones, even when using HTTP/2 or HTTP/3 (https://csswizardry.com/2023/10/the-three-c-concatenate-compress-cache/).

Using ckeditor5 also means less work for you, as you don't have to worry about bundling the packages yourself, dynamically updating the import maps, etc.

[bnf]

Thanks for your fast feedback. I'm confident we'll find workaround for TYPO3, but I still think that the new CKEditor5 module structure has some flaws and therefore I'd like to share this, although I fear I'm a bit late to the party. Maybe it's still helpful.
Please don't see this as a rant or alike, I understand if this is too late or if you disagree.

I got a bit of experience with different modules from migrating a large JavaScript codebase (TYPO3) to native ES6 importmap'd modules, where I worked around issues of a lot of JavaScript projects and saw good (e.g. https://lit.dev/ and https://codemirror.net/) packages and not so good ones in terms of "vanilla" usage in browser, without the mainstream bundlers webpack or vite… (optimizing for vanilla usage in a browser often helps to find the most clean and hackfree solution that therefore even works in all environments/bundlers without additonal hacks)

The ckeditor5 package exposes code from all packages and plugins as a single entrypoint, but the individual packages still directly depend on each other (e.g. @ckeditor/ckeditor5-core depends on @ckeditor/ckeditor5-engine and @ckeditor/ckeditor5-utils, not on ckeditor5). This means that in NIM it's still possible to use individual packages instead of ckeditor5 […].

Sounds pretty nice, but the packages still require the ckeditor5 package: https://cdn.jsdelivr.net/npm/@ckeditor/ckeditor5-table@0.0.0-nightly-20240517.0/package.json
That means: Each package now pulls in all other open source packages.

Furthermore, in NIM we already rewrite the imports like ckeditor5/src/core.js to @ckeditor/ckeditor5-core (during the build process, not in the source to maintain backwards compatibility).

Preserving BC sounds promising, but I wonder what is actually preserved here. In other words: what would actually break if the imports are corrected to @ckeditor/ckeditor5-*? Bundlers would have less work to do. We’d remove some workarounds, you’d remove release-script-overhead.
Do you know of a component that actually relies on the fact that imports are done indirectly through the (new umbrella) module ckeditor5?

Side-Question

Why did you decide to create a dist/ folder that contains compiled sources while src/ also contains compiled JavaScript as well? I guess that’s for backwards compatibility as well? (maybe because of pre-v37-style import Plugin from '@ckeditor/ckeditor5-core/src/plugin'; imports? – they wouldn't break IMO)

This new folder will not actually be used by bundlers as package.json of the scoped packages still refers to src/ in main field. That means it becomes breaking as soon as you switch main to dist instead of src. That means: There is no gain from the dist folder right now (no one will use it, only those who import from ckeditor5 instead of the scoped modules – will you update all of the documentation to refer to the umbrella module instead of the scoped modules?)

Inspecting https://cdn.jsdelivr.net/npm/ckeditor5@0.0.0-nightly-20240517.0/dist/index.js I'd really recommend to use

export * from '@ckeditor/ckeditor5-core';

instead of

export * from '@ckeditor/ckeditor5-core/dist/index.js';

…for the sake of a clear and hack-free module structure. This means you'll have less "environments" because all variants use the same sources and you avoid publishing two compiled variants (src and dist).
Also folders do not become API, but you define the bare module specifier to be API and control that via package.json exports.

For an example, see the nightly build of the @ckeditor/ckeditor5-table plugin here: https://cdn.jsdelivr.net/npm/@ckeditor/ckeditor5-table@nightly/dist/index.js.

I see two issues with this code:

• You have to apply the hack to import from a subpath @ckeditor/ckeditor-*/dist/index.js as you are using "main": "src/index.js" in package.json instead of "main": "dist/index.js".
• The TypeScript declarations (*.d.ts files) are not replaced and still reference the ckeditor5 package. (So we’ll likely not get rid of this circular dependency :()

Please consider changing main to dist/index.js and use bare module imports (import "@ckeditor/ckeditor-core", not "@ckeditor/ckeditor-core/path/to/entrypoint.js" and remove the dependency to ckeditor5 – or maybe just keep using src/*.js).

You’re changing module structure right now and I think you’ll regret this in some months if you apply intermediate hacks and do not fully migrate to a "clean" solution.
This new structure would be actually be a good fit for the v42 release (remember: pulling in alot more dependencies due to the transitive nature of the new umbrella-and-library package ckeditor5 will raise more bug reports).

Your approach

So what do you need to do to make your approach work with NIM?

First, you still need to build the packages yourself. While we provide npm, ES browser and UMD browser builds for the ckeditor5 package.

I’d love to avoid that processing on our side, therefore I named the example of codemirror v6 which does exactly the processing we do for CKEditor on their side during publishing – and you could actually do the same. (And I really think this would actually help to get to a clean solution without hacks/workarounds)

I would like to point out that the ckeditor5 package is still the recommended way to use CKEditor 5 for most projects,

I don't really understand that. The documentation refers to scoped modules (which is good!) all over the place. Where is ckeditor5 package the recommended way currently? Or do you plan to change that?

and that counter-intuitively it might offer better performance, even though it contains a bunch of plugins you don't use. It of course depends on the setup, but it's generally faster to load a single large file than multiple smaller ones, even when using HTTP/2 or HTTP/3 (https://csswizardry.com/2023/10/the-three-c-concatenate-compress-cache/).

We strive for runtime performance, not for fast time-to-first-uncached-rendering (important for sales sites, but runtime/cached performance is more important for applications – which is what we build and where I suppose CKEditor is used in exclusively). That means low RAM usage and small cacheable resources are important and smaller bundles are key to that.
We’d therefore love to continue using scoped-module imports instead of one big monolith.

[filipsobol]

This is great feedback and I agree with most of it. I also understand why parts of it might feel hacky at first glance, but nothing is done here without a reason. I'll try to explain some of the decisions we made.

Firstly, the last release did not introduce the new installation methods. The dist folder added to the bundles was, as we call it internally, a "silent release" for NIM. There's no official documentation for it, and it's not meant to be used in production yet. It's for us to test and prepare for the upcoming release.

Secondly, when we started working on NIM about 8 months ago, one of the very first decisions and requirements was to maintain backwards compatibility for some time to allow developers to migrate to the new version. The last thing we wanted was a Python 2 vs. Python 3 or AngularJS vs. Angular situation where a significant portion of projects were stuck on the old version. Even worse, we could introduce a new feature or security fix that requires a full migration to the new version.

This mindset explains some of the decisions we've made.

[...] what would actually break if the imports are corrected to @ckeditor/ckeditor5-*? Bundlers would have less work to do. We’d remove some workarounds, you’d remove release-script-overhead.
Do you know of a component that actually relies on the fact that imports are done indirectly through the (new umbrella) module ckeditor5?

In the old installation methods, we used ckeditor5/src/* packages to import code from core editor packages (core, engine, ui, etc.). This was necessary for the DLL builds to work properly.
Because we wanted to maintain backwards compatibility, we couldn't just change the imports to @ckeditor/ckeditor5-* packages in our source code. That would break the DLL builds and the projects that depend on them. However, we rewrite these imports when generating bundles for NIM.

Once we drop backwards compatibility, we'll be able to remove the ckeditor5/src/* imports and use direct imports instead.

Why did you decide to create a dist/ folder that contains compiled sources while src/ also contains compiled JavaScript as well? I guess that’s for backwards compatibility as well?

Yes, that's correct. The src folder is used to build the editor from source (using webpack or Vite). It contains code that has only been transpiled from TypeScript to JavaScript, but it's not ready to use as is because it requires plugins for parsing SVG, PostCSS, etc. The dist folder, however, contains the editor that can be used without any special setup.

This new folder will not actually be used by bundlers as package.json of the scoped packages still refers to src/ in main field. That means it becomes breaking as soon as you switch main to dist instead of src. That means: There is no gain from the dist folder right now (no one will use it, only those who import from ckeditor5 instead of the scoped modules – [...])

This is also done for the backwards compatibility. Once we drop support for the old methods, we will update the main field in the package.json files to point to the dist folder.

will you update all of the documentation to refer to the umbrella module instead of the scoped modules?
[...]
I don't really understand that. The documentation refers to scoped modules (which is good!) all over the place. Where is ckeditor5 package the recommended way currently? Or do you plan to change that?

Yes, we are in the process of rewriting large portions of the documentation to reflect the changes we've made. This is also part of our broader effort to improve the developer experience when working with CKEditor 5.

We're also working on migration guides to help developers migrate from the old version to the new one.

I’d love to avoid that processing on our side, therefore I named the example of codemirror v6 which does exactly the processing we do for CKEditor on their side during publishing – and you could actually do the same. (And I really think this would actually help to get to a clean solution without hacks/workarounds)

We'll internally discuss the possibility to publish browser builds for all individual packages, not only the ckeditor5.

[DeltekDavid]

We're trying to integrate the nightly build into our POC. We modeled it after the Vite-React example.

The sample code worked, but when we need things like custom plug-ins and real-time collab. Do those work with NIM yet? If we need the nightly builds of those, how can we reference those? For example we need ContextBase but not sure which package to pull that from which will work with NIM and nightly ckeditor5. Since the nightly ckeditor5 supplants a bunch of the separate packages (if I'm not mistaken) I wasn't sure which packages to just change to 'nightly' and which are folded into the main ckeditor5.

Hoping that when NIM is released soon, this will be a bit easier.

Thanks!

Update: I went ahead and referenced the nightly build of anything that wasn't found in the main ckeditor5, including ckeditor5-core for ContextBase. Now I have this error:

ERROR in ./node_modules/@ckeditor/ckeditor5-core/theme/icons/object-size-custom.svg
Module build failed (from ./node_modules/@svgr/webpack/lib/index.js):
SyntaxError: unknown file: Namespace tags are not supported by default. React's JSX doesn't support namespace tags. You can set `throwIfNamespace: false` to bypass this warning.

[Witoso]

When NIM is out, you only need to have ckeditor5 and ckeditor5-premium-features, and everything should be there to import from. We begin reviewing all collaboration documents and samples next week. This is a great find, and thanks for bringing it to our attention. We will start fixing this as soon as we can, and it should appear on nightly soon.

[Witoso]

@DeltekDavid forgive my Friday thinking, you can simply switch ContextBase to Context from the ckeditor5, and it should work. We are rewriting the docs.

[DeltekDavid]

Thanks @Witoso , I tried using Context instead of ContextBase and ClassicEditor instead of ClassicEditorBase. I also referenced Comments, TrackChanges, and the other premium things from ckeditor5-premium-features. Cleaned node_modules and reinstalled via yarn with just those two packages plus @ckeditor/ckeditor5-react and @ckeditor/ckeditor5-inspector. Install and compile succeeded, but when I run it crashes with:

ERROR
ckeditor-duplicated-modules
Read more: https://ckeditor.com/docs/ckeditor5/latest/support/error-codes.html#error-ckeditor-duplicated-modules
CKEditorError: ckeditor-duplicated-modules
Read more: https://ckeditor.com/docs/ckeditor5/latest/support/error-codes.html#error-ckeditor-duplicated-modules
    at ./node_modules/@ckeditor/ckeditor5-ui/node_modules/@ckeditor/ckeditor5-utils/dist/index.js (http://localhost:3000/static/js/bundle.js:1366465:9)
    at options.factory (http://localhost:3000/static/js/bundle.js:1450207:31)
    at __webpack_require__ (http://localhost:3000/static/js/bundle.js:1449606:32)
    at fn (http://localhost:3000/static/js/bundle.js:1449865:21)
    at ./node_modules/@ckeditor/ckeditor5-ui/dist/index.js (http://localhost:3000/static/js/bundle.js:1307617:97)
    at options.factory (http://localhost:3000/static/js/bundle.js:1450207:31)
    at __webpack_require__ (http://localhost:3000/static/js/bundle.js:1449606:32)
    at fn (http://localhost:3000/static/js/bundle.js:1449865:21)
    at ./node_modules/@ckeditor/ckeditor5-alignment/dist/index.js (http://localhost:3000/static/js/bundle.js:153105:94)
    at options.factory (http://localhost:3000/static/js/bundle.js:1450207:31)

[BrancuAlexandru]

This is actually really cool of you guys to do, thanks. I ran into extensibility issues this week with prebuilts, which are now entrenched into our codebase and now I have to bring up actual tehnical debt next time I talk to my superior.

[Witoso]

@DeltekDavid could you create a separate issue for this? I would rather not hijack the whole thread. The last idea I have is that you're using npm and running into peerDeps problem: ckeditor5-react pulls some misaligned deps as you're using the nightly. The simple fix is to use npm install --legacy-peer-deps

[DeltekDavid]

@DeltekDavid could you create a separate issue for this? I would rather not hijack the whole thread. The last idea I have is that you're using npm and running into peerDeps problem: ckeditor5-react pulls some misaligned deps as you're using the nightly. The simple fix is to use npm install --legacy-peer-deps

Thank you @Witoso , I got the packages to install with --legacy-peer-deps. I then got a Context Watchdog error on running the app. I created a tech support ticket to not derail the thread :D Thanks