v3.0.0-beta.79 (2024-08-14)
Features
- richtext-lexical: move migration related features to /migrate subpath export in order to decrease module count when those are not used (#7660) (a192632)
- filename compound index (#7651) (5fc9f76)
- beta-next (#7620) (90b7b20)
Bug Fixes
- richtext-lexical: inline blocks and tables not functioning correctly if they are used in more than one editor on the same page (#7665) (fca4ee9)
- live-preview: encode query string url (#7635) (9cb84c4)
BREAKING CHANGES
- richtext-lexical: move migration related features to /migrate subpath export in order to decrease module count when those are not used (#7660) (a192632)
This lowers the module count by 31 modules
BREAKING: Migration-related lexical modules are now exported from
@payloadcms/richtext-lexical/migrate
instead of
@payloadcms/richtext-lexical
-
To migrate from
beta.78
tobeta.79
, you'll need to make a few changes to your Payload Config. Although this release is substantial, migration is relatively straightforward and mostly effects the handling of Custom Components. These changes were necessary make the Payload Config 100% Node-safe, compile faster, and to increase type safety. For full details, check out the corresponding PR: #7620
For QA and discussion on this, please see the discussion: #7668.
Import Map
The following changes are required of all projects:
- Add a
/app/(payload)/admin/importMap.js
file to your app with the following content:
export const importMap {}
Payload will dynamically inject this file with imports at compile time. If you are using a custom admin route, change the path accordingly.
- Import this file into your Root Layout, Root Page, and Not Found Page:
The Root Layout at /app/(payload)/layout.tsx
:
// ...
import { importMap } from "../importMap.js"
//...
const Layout = ({ children }: Args) => (
<RootLayout config={configPromise} importMap={importMap}>
{children}
</RootLayout>
)
export default Layout
The Root Page at /app/(payload)/admin/[[...segments]]/page.tsx
:
// ...
import { importMap } from "../../../importMap.js"
//...
const Page = ({ params, searchParams }: Args) =>
RootPage({ config, importMap, params, searchParams })
export default Page
The Not Found Page at /app/(payload)/admin/[[...segments]]/not-found.tsx
:
// ...
import { importMap } from "../../../importMap.js"
//...
const NotFound = ({ params, searchParams }: Args) =>
NotFoundPage({ config, importMap, params, searchParams })
export default NotFound
- If you are importing the Payload Config in a Node.js environment, there is no longer a need for a special loader to process it. Instead, you can simply import the Payload Config directly. To migrate, remove the
importConfig
andimportWithoutClientFiles
functions from your Node.js code:
Old:
import { importConfig, importWithoutClientFiles } from "payload"
import { join } from "path"
const config = importConfig(join(__dirname, "payload.config.js"))
const configWithoutClientFiles = importWithoutClientFiles(
join(__dirname, "payload.config.js")
)
New:
import config from "./payload.config.js"
If you are not using Custom Components in your applications, then you are done! If you are using Custom Components, continue reading.
Custom Components
Here's a step-by-step overview of the remainder of the migration. Not all of these changes will apply to every project. If a change applies to yours, scroll to that section for a detailed breakdown.
Overview
If you have Custom Components in your Payload Config, one or more of these changes will apply to you:
- Update component imports to component paths
- Update
useConfig
hook usage (if applicable) - Update
useComponentMap
hook usage (if applicable) - Update Custom Field prop references (if applicable)
- Remove
useFieldProps
hook usage (if applicable) - Update Custom Views and Tabs keys (if applicable)
Step-by-Step
Here's a full breakdown of each step:
- If you are using Custom Components in your Payload Config, the pattern for defining them has changed. You'll need to update your Custom Component definitions to use "component paths" instead of direct imports. To migrate, pass the path to the component's file:
Old:
import { MyCustomComponent } from './MyCustomComponent.js'
// ...
{
// ...
admin: {
components: {
Label: MyCustomComponent
},
},
}
New:
{
// ...
admin: {
components: {
// NOTE: this path is relative to your `baseDir`, NOT the importing file
// The `#` character is used to specify the export name, if necessary
Label: '/collections/Posts/MyServerComponent.js#MyExportName',
},
},
}
Alternatively, you can also define the custom component as a "PayloadComponent" in the Payload Config. This allows you to pass in client-side vs server-side props explicitly, which get automatically sanitized from the client.
{
// ...
admin: {
components: {
Label: {
path: '/collections/Posts/MyServerComponent.js#MyExportName',
// exportName: 'MyComponent2' // optional if you wish to omit the export name from the path
clientProps: {
someClientProp: 'someValue'
},
serverProps: {
someServerProp: () => 'someValue'
}
}
},
},
}
- If you are using the
useConfig
React hook anywhere in your Custom Components, its return value has changed in shape. Theconfig
is now a property within the context object, rather than the return value itself. To migrate, simply destructure theconfig
property from the return value ofuseConfig
:
Old:
import { useConfig } from "@payloadcms/ui"
// ...
const config = useConfig()
New:
import { useConfig } from "@payloadcms/ui"
// ...
const { config } = useConfig()
- If you were using the
useComponentMap
React hook anywhere in your Custom Components, it no longer exists. Instead, it has been merged intouseConfig
. To migrate, swap it out for the new hook:
Old:
import { useComponentMap } from "@payloadcms/ui"
// ...
const { componentMap, getComponentMap } = useComponentMap()
const collectionComponentMap = getComponentMap({ collectionSlug: "pages" })
New:
import { useConfig } from "@payloadcms/ui"
// ...
const { config, getEntityConfig } = useConfig()
const collectionClientConfig = getEntityConfig({ collectionSlug: "pages" })
- If you were using Custom Fields anywhere in your code, their props have changed in shape. Previously, field props were spread in at the top-level of the component. Now, they are nested under the
field
key, which is a client-safe version of that field's config. To migrate, simply change your prop references to be nested underfield
:
Old:
import type { TextFieldProps } from "payload"
const MyCustomField: : React.FC<TextFieldProps> = ({ name }) => {
return <div>{name}</div>
}
New:
import type { TextFieldProps } from "payload"
const MyCustomField: : React.FC<TextFieldProps> = ({ field: { name } }) => {
return <div>{name}</div>
}
This example demonstrates a simple text field, but this same thing applies to all field types. The type naming convention is consistent across all field types, so you can easily find the type definitions for your respective field type.
- If you previously using the
useFieldProps
hook in your Custom Client Components, this is no longer needed. Now, client components are automatically detected and rendered client-side which direct props. To migrate your Custom Client Components, simply remove theuseFieldProps
hook from your and read directly from props:
Old:
"use client"
import type { TextFieldProps } from "payload"
import { useFieldProps } from "@payloadcms/ui"
const MyCustomClientComponent: React.FC<TextFieldProps> = () => {
const { path } = useFieldProps()
return <div>{path}</div>
}
New:
"use client"
import type { TextFieldProps } from "payload"
const MyCustomClientComponent: React.FC<TextFieldProps> = ({
field: { _path },
}) => {
return <div>{_path}</div>
}
- The shape of Custom Views and Custom Tabs has changed. Previously, you could define Custom Views and Tabs top-level in the config object OR as a configuration object. Now, you can only define them as a configuration object. For this reason, the keys have changed in casing to reflect the new shape (
CapitalCase
denotes a React component,camelCase
denotes a regular object). To migrate, simply change the casing of of these keys within your Payload Config:
Old:
{
// ...
admin: {
views: {
Edit: {
Default: {
Tab: MyCustomTab
},
API: MyCustomAPIView
}
}
}
}
New:
{
// ...
admin: {
views: {
edit: {
default: {
tab: {
// ...
}
},
api: {
// ...
}
}
}
}
}
This example demonstrates only a subset of the Custom Views that are available in the Payload Config. The same change applies to all Custom Views and Tabs, such as admin.views.account
at the root-level, or admin.views.list
on Collection Configs.
Contributors
- Alessio Gravili (@AlessioGr)
- Elliot DeNolf (@denolfe)
- Patrik (@PatrikKozak)