8
0

version.js 7.8 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155
  1. /**
  2. * @license Copyright (c) 2003-2020, CKSource - Frederico Knabben. All rights reserved.
  3. * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
  4. */
  5. /**
  6. * @module utils/version
  7. */
  8. /* globals window, global */
  9. import CKEditorError from './ckeditorerror';
  10. const version = '19.0.0';
  11. /* istanbul ignore next */
  12. const windowOrGlobal = typeof window === 'object' ? window : global;
  13. /* istanbul ignore next */
  14. if ( windowOrGlobal.CKEDITOR_VERSION ) {
  15. /**
  16. * This error is thrown when due to a mistake in how CKEditor 5 was installed or initialized, some
  17. * of its modules were duplicated (evaluated and executed twice). Module duplication leads to inevitable runtime
  18. * errors.
  19. *
  20. * There are many situations in which some modules can be loaded twice. In the worst case scenario,
  21. * you may need to check your project for each of these issues and fix them all.
  22. *
  23. * # Trying to add a plugin to an existing build
  24. *
  25. * If you import an existing CKEditor 5 build and a plugin like this:
  26. *
  27. * import ClassicEditor from '@ckeditor/ckeditor5-build-classic';
  28. * import Highlight from '@ckeditor/ckeditor5-highlight/src/highlight';
  29. *
  30. * Then your project loads some CKEditor 5 packages twice. How does it happen?
  31. *
  32. * The build package contains a file which is already compiled with webpack. This means
  33. * that it contains all the necessary code from e.g. `@ckeditor/ckeditor5-engine` and `@ckeditor/ckeditor5-utils`.
  34. *
  35. * However, the `Highlight` plugin imports some of the modules from these packages, too. If you ask webpack to
  36. * build such a project, you will end up with the modules being included (and run) twice — first, because they are
  37. * included inside the build package, and second, because they are required by the `Highlight` plugin.
  38. *
  39. * Therefore, **you must never add plugins to an existing build** unless your plugin has no dependencies.
  40. *
  41. * Adding plugins to a build is done by taking the source version of this build (so, before it was built with webpack)
  42. * and adding plugins there. In this situation, webpack will know that it only needs to load each plugin once.
  43. *
  44. * Read more in the {@glink builds/guides/integration/installing-plugins "Installing plugins"} guide.
  45. *
  46. * # Confused an editor build with an editor implementation
  47. *
  48. * This scenario is very similar to the previous one, but has a different origin.
  49. *
  50. * Let's assume that you wanted to use CKEditor 5 from source, as explained in the
  51. * {@glink builds/guides/integration/advanced-setup#scenario-2-building-from-source "Building from source"} section
  52. * or in the {@glink framework/guides/quick-start "Quick start"} guide of CKEditor 5 Framework.
  53. *
  54. * The correct way to do so is to import an editor and plugins and run them together like this:
  55. *
  56. * import ClassicEditor from '@ckeditor/ckeditor5-editor-classic/src/classiceditor';
  57. * import Essentials from '@ckeditor/ckeditor5-essentials/src/essentials';
  58. * import Paragraph from '@ckeditor/ckeditor5-paragraph/src/paragraph';
  59. * import Bold from '@ckeditor/ckeditor5-basic-styles/src/bold';
  60. * import Italic from '@ckeditor/ckeditor5-basic-styles/src/italic';
  61. *
  62. * ClassicEditor
  63. * .create( document.querySelector( '#editor' ), {
  64. * plugins: [ Essentials, Paragraph, Bold, Italic ],
  65. * toolbar: [ 'bold', 'italic' ]
  66. * } )
  67. * .then( editor => {
  68. * console.log( 'Editor was initialized', editor );
  69. * } )
  70. * .catch( error => {
  71. * console.error( error.stack );
  72. * } );
  73. *
  74. * However, you might have mistakenly imported a build instead of the source `ClassicEditor`. In this case
  75. * your imports will look like this:
  76. *
  77. * import ClassicEditor from '@ckeditor/ckeditor5-build-classic';
  78. * import Essentials from '@ckeditor/ckeditor5-essentials/src/essentials';
  79. * import Paragraph from '@ckeditor/ckeditor5-paragraph/src/paragraph';
  80. * import Bold from '@ckeditor/ckeditor5-basic-styles/src/bold';
  81. * import Italic from '@ckeditor/ckeditor5-basic-styles/src/italic';
  82. *
  83. * This creates the same situation as in the previous section because you use a build together with source plugins.
  84. *
  85. * Remember: `@ckeditor/ckeditor5-build-*` packages contain editor builds and `@ckeditor/ckeditor5-editor-*` contain source editors.
  86. *
  87. * # Loading two or more builds on one page
  88. *
  89. * If you use CKEditor 5 builds, you might have loaded two (or more) `ckeditor.js` files on one web page.
  90. * Check your web page for duplicated `<script>` elements or make sure your page builder/bundler includes CKEditor only once.
  91. *
  92. * If you want to use two different types of editors at once, see the
  93. * {@glink builds/guides/integration/advanced-setup#scenario-3-using-two-different-editors "Using two different editors"}
  94. * section.
  95. *
  96. * # Using outdated packages
  97. *
  98. * Building CKEditor 5 from source requires using multiple npm packages. These packages have their dependencies
  99. * to other packages. If you use the latest version of, for example, `@ckeditor/ckeditor5-editor-classic` with
  100. * an outdated version of `@ckeditor/ckeditor5-image`, npm or yarn will need to install two different versions of
  101. * `@ckeditor/ckeditor5-core` because `@ckeditor/ckeditor5-editor-classic` and `@ckeditor/ckeditor5-image` may require
  102. * different versions of the core package.
  103. *
  104. * The solution to this issue is to update all packages to their latest version. We recommend
  105. * using tools like [`node-check-updates`](https://www.npmjs.com/package/npm-check-updates) which simplify this process.
  106. *
  107. * # Conflicting version of dependencies
  108. *
  109. * This is a special case of the previous scenario. If you use CKEditor 5 with some third-party plugins,
  110. * it may happen that even if you use the latest versions of the official packages and the latest version of
  111. * these third-party packages, there will be a conflict between some of their dependencies.
  112. *
  113. * Such a problem can be resolved by either downgrading CKEditor 5 packages (which we do not recommend) or
  114. * asking the author of the third-party package to upgrade its depdendencies (or forking their project and doing this yourself).
  115. *
  116. * **Note:** All official CKEditor 5 packages (excluding integrations and `ckeditor5-dev-*` packages) are released in the
  117. * same major version. This is &mdash; in the `x.y.z`, the `x` is the same for all packages. This is the simplest way to check
  118. * whether you use packages coming from the same CKEditor 5 version. You can read more about versioning in the
  119. * {@glink framework/guides/support/versioning-policy Versioning policy} guide.
  120. *
  121. * # Packages were duplicated in `node_modules`
  122. *
  123. * In some situations, especially when calling `npm install` multiple times, it may happen
  124. * that npm will not correctly "deduplicate" packages.
  125. *
  126. * Normally, npm deduplicates all packages so, for example, `@ckeditor/ckeditor5-core` is installed only once in `node_modules/`.
  127. * However, it is known to fail to do so from time to time.
  128. *
  129. * We recommend checking if any of the steps listed below help:
  130. *
  131. * * `rm -rf node_modules && npm install` to make sure you have a clean `node_modules/` directory. This step
  132. * is known to help in most cases.
  133. * * If you use `yarn.lock` or `package-lock.json`, remove it before `npm install`.
  134. * * Check whether all CKEditor 5 packages are up to date and reinstall them
  135. * if you changed anything (`rm -rf node_modules && npm install`).
  136. *
  137. * If all packages are correct and compatible with each other, the steps above are known to help. If not, you may
  138. * try to check with `npm ls` how many times packages like `@ckeditor/ckeditor5-core`, `@ckeditor/ckeditor5-engine` and
  139. *`@ckeditor/ckeditor5-utils` are installed. If more than once, verify which package causes that.
  140. *
  141. * @error ckeditor-duplicated-modules
  142. */
  143. throw new CKEditorError(
  144. 'ckeditor-duplicated-modules: Some CKEditor 5 modules are duplicated.',
  145. null
  146. );
  147. } else {
  148. windowOrGlobal.CKEDITOR_VERSION = version;
  149. }