diff --git a/docs/source/upgrade-guide/index.md b/docs/source/upgrade-guide/index.md index 3da7fbb39a..60de994f58 100644 --- a/docs/source/upgrade-guide/index.md +++ b/docs/source/upgrade-guide/index.md @@ -522,6 +522,142 @@ The `react/jsx-key` rule has been enabled in ESlint for catching missing `key` i You might catch some violations in your project or add-on code after running ESlint. Adding the missing `key` property whenever the violation is reported will fix it. +### Deprecation notices for Volto 18 + +#### `@plone/generator-volto` + +```{deprecated} Volto 18.0.0 +``` + +The Node.js-based Volto project boilerplate generator is deprecated from Volto 18 onwards. +After the release of Volto 18, it will be marked as deprecated, archived, and it won't receive any further updates. +Although you can still migrate your project to Volto 18 using this boilerplate, you should migrate to using [Cookieplone](https://github.com/plone/cookieplone). + +##### Alternative + +Migrate your project to use a [Cookieplone](https://github.com/plone/cookieplone) boilerplate. + +#### Volto project configurations + +```{deprecated} Volto 18.0.0 +``` + +Configuring Volto using {file}`src/config.js` at the project level is deprecated in Volto 18, and will be removed in Volto 19. + +```{seealso} +See https://github.com/plone/volto/issues/6396 for details. +``` + +##### Alternative + +You should configure your projects in a policy add-on. +You can move your project to use [Cookieplone](https://github.com/plone/cookieplone) which provides the necessary boilerplate for it. + +#### Semantic UI + +```{deprecated} Volto 18.0.0 +``` + +The Semantic UI library is not maintained anymore, and will be removed in Plone 7. +You should no longer use Semantic UI in add-ons and projects. + +```{seealso} +Related PLIPs: + +- https://github.com/plone/volto/issues/6321 +- https://github.com/plone/volto/issues/6323 +``` + +##### Alternatives + +You can use any supported component framework of your choice for implementing new components, especially in the public theme side. +If you create new widgets or components for the CMSUI—in other words, the non-public side—you should use the [`@plone/components`](https://github.com/plone/volto/tree/main/packages/components) library as an alternative. +Even though it's still in the development phase, it will be completed in the next few months, and will be supported in the future. + +#### `lodash` library + +```{deprecated} Volto 18.0.0 +``` + +`lodash` is deprecated in Volto 18, and will be removed in Plone 7. + +`lodash` has not received any updates since 2021. +It has performance issues from bloated bundles and it's not prepared for ESM. +Lots of `lodash` utility helpers can be replaced with vanilla ES. +These issues cause concern about its future maintainability. + +In place of `lodash`, Plone 7 will use both the `lodash-es` library, which is ESM ready, and modern vanilla ES alternatives whenever possible. + +##### Alternatives + +```{seealso} +The following links suggest alternatives to `lodash`. + +- https://github.com/you-dont-need/You-Dont-Need-Lodash-Underscore +- https://javascript.plainenglish.io/you-dont-need-lodash-how-i-gave-up-lodash-693c8b96a07c + +If you still need some of the utilities in `lodash` and cannot use vanilla ES, you can use `lodash-es` instead. +``` + +#### `@loadable/component` and Volto `Loadables` framework + +```{deprecated} Volto 18.0.0 +``` + +`@loadable/component` and the Volto `Loadables` framework is deprecated in Volto 18, and will be removed from Plone 7. +It's a Webpack-only library, and it does not have Vite plugin support. +Since React 18, this library is no longer necessary, as it has the initial implementation of the "concurrent mode". +React 19 will further improve it and add more features around it. + +##### Alternatives + +Use plain React 18 lazy load features and its idioms for lazy load components. + +```jsx +const myLazyComponent = lazy(()=> import('@plone/volto/components/theme/MyLazyComponent/MyLazyComponent')) + +const RandomComponent = (props) => ( + + + +) +``` + +There's no support for pre-loading or lazy loading entire libraries as in `@loadable/component`. +With the removal of barrel imports files, as described in the next deprecation notice, it is now unnecessary. + +#### Removal of barrel import files + +```{deprecated} Volto 18.0.0 +``` + +Volto previously used barrel imports, which are centralized files where other imports are re-exported, to improve the developer user experience. +With barrel imports, a developer only needs to remember to import from the re-exported place, not the full path. + +Since the barrel imports directly import all the code, a lot of imports ended up in the same main chunk of code. +It became a bad practice. +Modern bundlers, such as Vite, rely upon the import path to determine whether to bundle code together or not, reducing the bundle size. + +The barrel imports must be removed to increase the natural number of chunks that Volto divides on—especially on routes—resulting in code splitting done the right and natural way. +This forces us to rewrite all the imports everywhere—including core, projects, and add-ons—once we implement it. +The barrel imports files include the following. + +- {file}`src/components/index.js` +- {file}`src/helpers/index.js` +- {file}`src/actions/index.js` + +##### Alternative + +Implement only direct imports in code, preparing now for the upcoming change. + +```diff +-import { BodyClass } from '@plone/volto/helpers'; ++import BodyClass from '@plone/volto/helpers/BodyClass/BodyClass'; +``` + +Once this is implemented, a code modification will be provided for a smooth migration. + + (volto-upgrade-guide-17.x.x)= ## Upgrading to Volto 17.x.x diff --git a/packages/volto/news/6426.documentation b/packages/volto/news/6426.documentation new file mode 100644 index 0000000000..dc5079729a --- /dev/null +++ b/packages/volto/news/6426.documentation @@ -0,0 +1 @@ +Added deprecation notices to the upgrade guide for Volto 18. @sneridagh