From 4e275ddd30c8d0c44bc03b40f1cab0ffc26c4600 Mon Sep 17 00:00:00 2001 From: Filip Sobol Date: Fri, 30 Aug 2024 15:35:23 +0200 Subject: [PATCH 1/3] Docs: Add `Using bundlers to bundle CKEditor 5` document. --- docs/getting-started/setup/using-bundlers.md | 116 +++++++++++++++++++ 1 file changed, 116 insertions(+) create mode 100644 docs/getting-started/setup/using-bundlers.md diff --git a/docs/getting-started/setup/using-bundlers.md b/docs/getting-started/setup/using-bundlers.md new file mode 100644 index 00000000000..57790de6e84 --- /dev/null +++ b/docs/getting-started/setup/using-bundlers.md @@ -0,0 +1,116 @@ +--- +category: setup +meta-title: Using bundlers | CKEditor 5 documentation +order: 130 +modified_at: 2024-08-30 +--- + +# Using bundlers to bundle CKEditor 5 + +This guide will show you how to configure popular bundlers like **Vite**, **esbuild**, **Rollup**, and **webpack** to build applications using CKEditor 5. Showing how to set up or use these bundlers is not the goal of this guide. + +Note that CKEditor 5 ships plain ES2022 JavaScript modules and CSS files. Therefore, with recent enough bundlers, you should be able to use CKEditor 5 without any additional configuration. Or – in the case of Rollup and webpack – only with a standard set of plugins. + +## Bundling CKEditor 5 with Vite + +There is no need for any special configuration to bundle CKEditor 5 with recent versions of Vite. Follow the {@link getting-started/quick-start#installing-ckeditor-5-using-npm npm installation guide} to learn more. + +## Bundling CKEditor 5 with esbuild + +Similarly, you need no special configuration to bundle CKEditor 5 with recent versions of esbuild. Follow the {@link getting-started/quick-start#installing-ckeditor-5-using-npm npm installation guide} to learn more. + +## Bundling CKEditor 5 with Rollup + +To bundle CKEditor 5 with Rollup, you need to install the following plugins: + +1. `@rollup/plugin-node-resolve` – to allow Rollup to resolve dependencies. +2. `@rollup/plugin-commonjs` – to convert CommonJS modules to ES6. +3. `rollup-plugin-import-css` or `rollup-plugin-styles` – to allow Rollup to handle CSS files. +4. `@rollup/plugin-json` – to allow Rollup to handle JSON files. +5. `@rollup/plugin-terser` – to minify the output. + +Here is an example `rollup.config.js` file: + +```js +// rollup.config.js +import { defineConfig } from 'rollup'; +import json from '@rollup/plugin-json'; +import terser from '@rollup/plugin-terser'; +import css from 'rollup-plugin-import-css'; +import commonjs from '@rollup/plugin-commonjs'; +import { nodeResolve } from '@rollup/plugin-node-resolve'; + +const sourceMap = true; // Change depending on your needs. +const minify = true; // Change depending on your needs. + +export default defineConfig( { + // Other options are omitted for better readability. + plugins: [ + commonjs( { + sourceMap, + defaultIsModuleExports: true + } ), + nodeResolve( { + browser: true, + preferBuiltins: false + } ), + json(), + css( { + minify + } ), + minify && terser( { + sourceMap + } ) + ] +} ); +``` + +## Bundling CKEditor 5 with webpack + +To bundle CKEditor 5 with webpack, you need to install the following plugins: + +1. `mini-css-extract-plugin` – to extract CSS to a separate file. +2. `css-minimizer-webpack-plugin` – to minify CSS. +3. `terser-webpack-plugin` – to minify JavaScript. + +Here is an example `webpack.config.js` file: + +```js +// webpack.config.js +const path = require( 'path' ); +const MiniCssExtractPlugin = require( 'mini-css-extract-plugin' ); +const CssMinimizerPlugin = require( 'css-minimizer-webpack-plugin' ); +const TerserPlugin = require( 'terser-webpack-plugin' ); + +const sourceMap = true; // Change depending on your needs. +const minify = true; // Change depending on your needs. + +module.exports = { + // Other options are omitted for better readability. + optimization: { + minimize: minify, + minimizer: [ + new TerserPlugin(), + new CssMinimizerPlugin() + ] + }, + plugins: [ + new MiniCssExtractPlugin() + ], + module: { + rules: [ + { + test: /\.css$/i, + use: [ + MiniCssExtractPlugin.loader, + 'css-loader' + ] + } + ] + } +}; +``` + +Some setups and meta-frameworks based on webpack (such as Next.js), may use `babel-loader` to transpile JavaScript to a lower version. If the version of `babel-loader`, `@babel/core`, and `@babel/preset-env` are recent enough, you should be able to use CKEditor 5 without any additional configuration. However, projects using older versions of these packages may encounter the `Module parse failed: Unexpected token` error. It is caused by some ES2022 features that CKEditor 5 uses, such as native class properties. To address this issue, you need to add the [`@babel/plugin-proposal-class-properties`](https://babeljs.io/docs/babel-plugin-transform-class-properties) plugin to your Babel configuration. + +However, to avoid similar issues when CKEditor 5 starts using other modern features in the future, we recommend updating `babel-loader`, `@babel/core`, and `@babel/preset-env` to the latest possible versions. From 325e7badaec64decb3b1e2579893d11aa4c61351 Mon Sep 17 00:00:00 2001 From: Filip Sobol Date: Mon, 2 Sep 2024 10:31:40 +0200 Subject: [PATCH 2/3] Apply suggestions from code review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Mateusz Gorzeliński --- docs/getting-started/setup/using-bundlers.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/getting-started/setup/using-bundlers.md b/docs/getting-started/setup/using-bundlers.md index 57790de6e84..6efa74ed848 100644 --- a/docs/getting-started/setup/using-bundlers.md +++ b/docs/getting-started/setup/using-bundlers.md @@ -1,11 +1,12 @@ --- category: setup meta-title: Using bundlers | CKEditor 5 documentation +menu-title: Using bundlers order: 130 modified_at: 2024-08-30 --- -# Using bundlers to bundle CKEditor 5 +# Using bundlers to bundle the editor. This guide will show you how to configure popular bundlers like **Vite**, **esbuild**, **Rollup**, and **webpack** to build applications using CKEditor 5. Showing how to set up or use these bundlers is not the goal of this guide. @@ -111,6 +112,6 @@ module.exports = { }; ``` -Some setups and meta-frameworks based on webpack (such as Next.js), may use `babel-loader` to transpile JavaScript to a lower version. If the version of `babel-loader`, `@babel/core`, and `@babel/preset-env` are recent enough, you should be able to use CKEditor 5 without any additional configuration. However, projects using older versions of these packages may encounter the `Module parse failed: Unexpected token` error. It is caused by some ES2022 features that CKEditor 5 uses, such as native class properties. To address this issue, you need to add the [`@babel/plugin-proposal-class-properties`](https://babeljs.io/docs/babel-plugin-transform-class-properties) plugin to your Babel configuration. +Some setups and meta-frameworks based on webpack (such as Next.js), may use a `babel-loader` to transpile JavaScript to a lower version. If the version of `babel-loader`, `@babel/core`, and `@babel/preset-env` are recent enough, you should be able to use CKEditor 5 without any additional configuration. However, projects using older versions of these packages may encounter the `Module parse failed: Unexpected token` error. It is caused by some ES2022 features that CKEditor 5 uses, such as native class properties. You need to add the [`@babel/plugin-proposal-class-properties`](https://babeljs.io/docs/babel-plugin-transform-class-properties) plugin to your Babel configuration to address this issue. However, to avoid similar issues when CKEditor 5 starts using other modern features in the future, we recommend updating `babel-loader`, `@babel/core`, and `@babel/preset-env` to the latest possible versions. From 5067bc045572b66770103493be50e5e02aeab669 Mon Sep 17 00:00:00 2001 From: Filip Sobol Date: Mon, 2 Sep 2024 10:59:46 +0200 Subject: [PATCH 3/3] Reorder lists of require plugins to match the code snippets --- docs/getting-started/setup/using-bundlers.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/getting-started/setup/using-bundlers.md b/docs/getting-started/setup/using-bundlers.md index 6efa74ed848..ea4e663fcca 100644 --- a/docs/getting-started/setup/using-bundlers.md +++ b/docs/getting-started/setup/using-bundlers.md @@ -24,10 +24,10 @@ Similarly, you need no special configuration to bundle CKEditor 5 with rece To bundle CKEditor 5 with Rollup, you need to install the following plugins: -1. `@rollup/plugin-node-resolve` – to allow Rollup to resolve dependencies. -2. `@rollup/plugin-commonjs` – to convert CommonJS modules to ES6. -3. `rollup-plugin-import-css` or `rollup-plugin-styles` – to allow Rollup to handle CSS files. -4. `@rollup/plugin-json` – to allow Rollup to handle JSON files. +1. `@rollup/plugin-commonjs` – to convert CommonJS modules to ES6. +2. `@rollup/plugin-node-resolve` – to allow Rollup to resolve dependencies. +3. `@rollup/plugin-json` – to allow Rollup to handle JSON files. +4. `rollup-plugin-import-css` or `rollup-plugin-styles` – to allow Rollup to handle CSS files. 5. `@rollup/plugin-terser` – to minify the output. Here is an example `rollup.config.js` file: @@ -35,11 +35,11 @@ Here is an example `rollup.config.js` file: ```js // rollup.config.js import { defineConfig } from 'rollup'; -import json from '@rollup/plugin-json'; -import terser from '@rollup/plugin-terser'; -import css from 'rollup-plugin-import-css'; import commonjs from '@rollup/plugin-commonjs'; import { nodeResolve } from '@rollup/plugin-node-resolve'; +import json from '@rollup/plugin-json'; +import css from 'rollup-plugin-import-css'; +import terser from '@rollup/plugin-terser'; const sourceMap = true; // Change depending on your needs. const minify = true; // Change depending on your needs. @@ -79,9 +79,9 @@ Here is an example `webpack.config.js` file: ```js // webpack.config.js const path = require( 'path' ); -const MiniCssExtractPlugin = require( 'mini-css-extract-plugin' ); -const CssMinimizerPlugin = require( 'css-minimizer-webpack-plugin' ); const TerserPlugin = require( 'terser-webpack-plugin' ); +const CssMinimizerPlugin = require( 'css-minimizer-webpack-plugin' ); +const MiniCssExtractPlugin = require( 'mini-css-extract-plugin' ); const sourceMap = true; // Change depending on your needs. const minify = true; // Change depending on your needs.