Neos 4.0 is the next major version and comes with numerous changes, and a few additional features. Since some refactoring has happeend, developers will need to get familiar with a few changes.

Assets sources support for Neos Media

With this feature it is now possible to integrate remote asset libraries into Neos own media browser. You can search through these assets and import them into Neos for usage in the website. Adapters making use of this are currently being build, but the API is available for your integrations as well.

“DocumentType” rendering entry point for Fusion

If you provide a Fusion prototype with the same name as your Document NodeType, it will automatically be used for rendering those Document Nodes now. This aligns Document rendering with the way Content rendering happens by default and so should make it easier to use and understand.

In general we favor using of a prototype for rendering documents now instead of paths (like the “page” fusion path). To that effect a newly created site will now only have a prototype for a (also created) custom Document NodeType.

Change default charset and collation to utf8mb4

We now use utf8mb4 in MySQL compatible database to store strings. That means you can now use the full range of unicode characters anywhere and especially in Neos content. Yes, also emoji 😂

It also means your existing database must be updated to the new charset.

Layout is now only supported with the NodeTypes package

We consider the layout property not a best practice, and therefore recommend not using it and relying on NodeTypes instead. To allow for backwards compatibility the matcher that automatically renders a fusion path with the same name as layout / sublayout is not removed yet though but moved to the NodeTypes package that makes use of it in the Page NodeType declared in that package. The NodeTypes package itself is also not recommended as best practice. Instead create your own set of NodeTypes, maybe based on the Neos.NodeTypes.BaseMixins package.

Font Awesome 5 usage

We switched to the free version of the latest Font Awesome, that means more icons for you to use but also that you need to adapt to Font Awesome 5 icons and notation. You need to adapt custom backend modules by simply using the new icon classes as seen on https://fontawesome.com/ . The icon- prefix way of defining NodeType icons still works fine, but you can also switch to FA5 notation to get more specific about the icon you want. This change was made for the legacy and React UI as well as the Neos backend modules.

Upgrade instructions

See https://www.neos.io/download-and-extend/upgrade-instructions-3-3-4-0.html

!!! Breaking changes

As this is a major release a few breaking changes have gone in. All of them can be found in the ChangeLog, but everything important should be listed above and in the upgrade instructions.

In case you have any problems with this guide, please get in touch with us via discuss.neos.io or on Slack.


Additionally all changes in Flow 5.0 apply, see the release notes to further information. See http://flowframework.readthedocs.org/en/5.0/TheDefinitiveGuide/PartV/ReleaseNotes/500.html