v3.0.0-beta.49 (2024-06-17)
Features
🚧 BREAKING CHANGES
New file import locations
Exports from the payload package have been significantly cleaned up. Now, just about everything is able to be imported from payload directly, rather than an assortment of subpath exports. This means that things like import { buildConfig } from 'payload/config' are now just imported via import { buildConfig } from 'payload'. The mental model is significantly simpler for developers, but you might need to update some of your imports.
Payload now exposes only three exports:
payload- all types and server-only Payload codepayload/shared- utilities that can be used in either the browser or in Node environmentspayload/node- heavy utilities that should only be imported in Node scripts and never be imported into bundled code like Next.js
UI library pre-bundling
With this release, we've dramatically sped up the compile time for Payload by pre-bundling our entire UI package for use inside of the Payload admin itself. There are new exports that should be used within Payload custom components:
@payloadcms/ui/client- all client components@payloadcms/ui/server- all server components
For all of your custom Payload admin UI components, you should be importing from one of these two pre-compiled barrel files rather than importing from the more deeply nested exports directly. That will keep compile times nice and speedy, and will also make sure that the bundled JS for your admin UI is kept small.
For example, whereas before, if you imported the Payload Button, you would have imported it like this:
import { Button } from '@payloadcms/ui/elements/Button'Now, you would import it like this:
import { Button } from '@payloadcms/ui/client'This is a significant DX / performance optimization that we're pretty pumped about.
However, if you are importing or re-using Payload UI components outside of the Payload admin UI, for example in your own frontend apps, you can import from the individual component exports which will make sure that the bundled JS is kept to a minimum in your frontend apps. So in your own frontend, you can continue to import directly to the components that you want to consume rather than importing from the pre-compiled barrel files.
Individual component exports will now come with their corresponding CSS and everything will work perfectly as-expected.
Specific exports have changed
'@payloadcms/ui/templates/Default'and'@payloadcms/ui/templates/Minimal' are now exported from'@payloadcms/next/templates'- Some components are now more explicitly named while being exported, such as the
LogOuticon. Old:import { LogOut } from '@payloadcms/ui/icons/LogOut'New:import { LogOutIcon } from '@payloadcms/ui/icons/LogOut'
Background info
In effort to make local dev as fast as possible, we need to import as few files as possible so that the compiler has less to process. One way we've achieved this in the Admin Panel was to remove all .scss imports from all components in the @payloadcms/ui module using a build process. This stripped all import './index.scss' statements out of each component before injecting them into dist. Instead, it bundles all of the CSS into a single main.css file, and we import that at the root of the app.
While this concept is still the right solution to the problem, this particular approach is not viable when using these components outside the Admin Panel, where not only does this root stylesheet not exist, but where it would also bloat your app with unused styles. Instead, we need to keep these .scss imports in place so they are imported directly alongside your components, as expected. Then, we need create a new build step that separately compiles the components without their stylesheets—this way your app can consume either as needed from the new client and server barrel files within @payloadcms/ui, i.e. from within @payloadcms/next and all other admin-specific packages and plugins.
This way, all other applications will simply import using the direct file paths, just as they did before. Except now they come with stylesheets.
And we've gotten a pretty awesome initial compilation performance boost.
Contributors
- Jacob Fletcher (@jacobsfletch)