Component Import Map - Payload v3.0.0-beta.79 Breaking Changes

[DanRibbens]

On the topic of https://github.com/payloadcms/payload/releases/tag/v3.0.0-beta.79 we made a large change. This discussion is for QA and general feedback to help anyone making the update.

[clover0916]

Has this release fixed the bug that caused the admin panel to hang in production?

[AlessioGr]

Yep

[Timothylp]

We are currently attempting to migrate from payload beta 74 to beta 79. So far, we have removed all of our custom components and have successfully added the importMap file. However, when starting the development server, we are encountering numerous errors such as:
getCreateMappedComponent: Component not found in importMap { identifier: 'incomingField.editor.FieldComponent', key: undefined } getComponent: Component not found in importMap { identifier: 'incomingField.editor.CellComponent', key: '@payloadcms/richtext-lexical/client#RichTextCell', payloadComponent: { clientProps: { admin: undefined, lexicalEditorConfig: [Object] }, path: '@payloadcms/richtext-lexical/client#RichTextCell' } }

To conclude by :
⨯ Error: Functions cannot be passed directly to Client Components unless you explicitly expose it by marking it with "use server". Or maybe you meant to call this function rather than return it. {condition: function condition} ^^^^^^^^^^^^^^^^^^ at stringify (<anonymous>) at AsyncResource.runInAsyncScope (node:async_hooks:206:9) digest: "2168502112"

A big congratulations to the teams for the work accomplished; we have been eagerly awaiting these breaking changes.

[AlessioGr]

Just released beta.81, should be fixed there

[dinhmai74]

anyone got this error ? I do not have that package in my repo 😞

> cross-env NODE_OPTIONS=--no-deprecation payload "generate:importmap"


node:internal/process/promises:391
    triggerUncaughtException(err, true /* fromPromise */);
    ^
TypeError [ERR_UNKNOWN_FILE_EXTENSION]: Unknown file extension ".css" for /home/dinhmai/workspace/project/seo/payload-master/node_modules/.pnpm/[email protected][email protected]/node_modules/react-image-crop/dist/ReactCrop.css
    at Object.getFileProtocolModuleFormat [as file:] (node:internal/modules/esm/get_format:160:9)
    at defaultGetFormat (node:internal/modules/esm/get_format:203:36)
    at defaultLoad (node:internal/modules/esm/load:143:22)
    at async nextLoad (node:internal/modules/esm/hooks:866:22)
    at async load (file:///home/dinhmai/workspace/project/seo/payload-master/node_modules/.pnpm/[email protected]/node_modules/tsx/dist/esm/index.mjs?1723688364831:2:1762)
    at async nextLoad (node:internal/modules/esm/hooks:866:22)
    at async Hooks.load (node:internal/modules/esm/hooks:449:20)
    at async handleMessage (node:internal/modules/esm/worker:196:18) {
  code: 'ERR_UNKNOWN_FILE_EXTENSION'
}

Node.js v20.15.1

[foxted]

I got this error as well, but disabling my custom component solves the issue. My guess is it has to do with how the custom components are imported. On that note, @AlessioGr, do we have rationale behind using a string path for custom components, as opposed to a direct import?

[AlessioGr]

"do we have rationale behind using a string path for custom components, as opposed to a direct import?"

that css error is the reason. Using paths instead of actual imports will make sure that the config is node-safe and we do not import client code like CSS files into our config. Node.js will throw this error if that happens.
Previously, we allowed it - but we had to write a complex node loader to allow that, which had other negative side-effects.

If you still get an error such as "Unknown file extension ".css"", this means your config is not fully migrated to the new pattern. You likely still have some component imports somewhere, or you're using an older plugin which still imports client-side code

[foxted]

That makes sense. I managed to fix the css error, it was caused by a custom component that still had the old props reference, this new structure works:

export const SlugField: React.FC<TextFieldProps> = ({
  field: { _path: path, required, admin: { custom, placeholder } = {} },
}) => {
    // ...
}

[dinhmai74]

Custom features is not working, is there any update on it?

[dinhmai74]

✘ Type 'FC' is not assignable to type 'PayloadComponent<never, { featureKey: string; order: number; }> | undefined'.

// feature.server.ts
import { createServerFeature } from '@payloadcms/richtext-lexical'
import { EmbedFeatureClient } from './feature.client'
import { EmbedNode } from './nodes/EmbedNode'
import { Field, TextField } from 'payload'

const urlField: TextField = {
  name: 'url',
  type: 'text',
  required: true,
}

export const EmbedFeature = createServerFeature({
  feature: {
    ClientFeature: EmbedFeatureClient,
    nodes: [
      {
        node: EmbedNode,
      },
    ],
    generateSchemaMap: () => {
      const schemaMap = new Map<string, Field[]>()

      const fields = [urlField]
      schemaMap.set('fields', fields)

      return schemaMap
    },
  },
  key: 'embed',
})
```

Client file
```
// feature.client.ts

'use client'

import {
  createClientFeature,
  slashMenuBasicGroupWithItems,
  toolbarAddDropdownGroupWithItems,
} from '@payloadcms/richtext-lexical/client'
import { EmbedIcon } from './icons/EmbedIcon'
import { EmbedNode, OPEN_EMBED_DRAWER_COMMAND } from './nodes/EmbedNode'
import { EmbedPlugin } from './plugins'

export const EmbedFeatureClient = createClientFeature({
  plugins: [
    {
      Component: EmbedPlugin,
      position: 'normal',
    },
  ],
  nodes: [EmbedNode as any],
  toolbarFixed: {
    groups: [
      toolbarAddDropdownGroupWithItems([
        {
          key: 'embed',
          ChildComponent: EmbedIcon,
          label: 'Embed',
          onSelect: ({ editor }) => {
            editor.dispatchCommand(OPEN_EMBED_DRAWER_COMMAND, {})
          },
        },
      ]),
    ],
  },
  slashMenu: {
    groups: [
      slashMenuBasicGroupWithItems([
        {
          key: 'embed',
          label: 'Embed',
          onSelect: ({ editor }) => {
            editor.dispatchCommand(OPEN_EMBED_DRAWER_COMMAND, {})
          },
          keywords: ['embed'],
          Icon: EmbedIcon,
        },
      ]),
    ],
  },
})```

[dinhmai74]

Can you please provide more info on what you're seeing?

show errors ✘ Type 'FC<any>' is not assignable to type 'PayloadComponent<never, { featureKey: string; order: number; }> | undefined'. when passing the client component ``` ClientFeature: EmbedFeatureClient,

[AlessioGr]

EmbedFeatureClient counts as a custom component and will have to be migrated to paths just like any other custom components you might have in the config. PayloadComponent = component path

[megetron3]

not sure how to addd this custom component, can i have an example of what needs to be changes?

[megetron3]

for those who run into it, after reading the docs and looking on how the payload team implemented the other custom components, succeeded solving this:
changr this on the server:

ClientFeature: 'src/embedFeature/feature.client#EmbedFeatureClient',

make sure you importMap.js doesn't already have your previous import, if they exists you might need to delete manually.

on your payload.config.ts add this to the root:

  admin: { 
    components: {
      "feature.client": {
        Embed: 'src/embedFeature/feature.client#EmbedFeatureClient'
      }
    }
  },

for those how looking for an updated version of paload(3.0.0-beta.108) of the embed feature i created a cloned version:
also opened a new pull request to fix it:
https://github.com/payloadcms/lexical-embed-feature/pull/1/files

[nlvogel]

Trying to get custom Logo and Icon components working in my payload.config and running into issues.

admin: {
    components: {
      graphics: {
        Icon: { path: '/src/graphics/Icon.tsx', exportName: 'Icon' },
        Logo: { path: '/src/graphics/Logo.tsx', exportName: 'Logo' },
      },
    },
...
}

I've tried both with the # export name and what you see above.
I tried pnpm payload generate:importmap and get Error: addToImportMap > Payload component must be an object or a string.
My code runs but it throws an error and doesn't show my custom components.

My components look like this:

Logo.tsx

import React from 'react'
import Image from 'next/image'

export const Logo = () => {
  const iconUrl = `${process.env.S3}/lvc-primary-full.svg`
  const darkIconUrl = `${process.env.S3}/lvc-primary-inverse.svg`

  return (
    <picture>
      <source width={919} height={303} src={darkIconUrl} media={'(prefers-color-scheme: dark)'} />
      <Image
        loading={'eager'}
        style={{
          position: 'unset',
        }}
        width={919}
        height={303}
        src={iconUrl}
        alt={'LVC Logo'}
      />
    </picture>
  )
}

[nlvogel]

I have a lot of these to fix, but these are the most important to me. The error I get for the Logo import is this:

getComponent: Component not found in importMap {
  identifier: 'CustomLogo',
  key: '/src/graphics/Logo.tsx#Logo',
  payloadComponent: { path: '/src/graphics/Logo.tsx', exportName: 'Logo' }
}
getCreateMappedComponent: Component not found in importMap { identifier: 'CustomLogo', key: undefined }

[AlessioGr]

@nlvogel

Error: addToImportMap > Payload component must be an object or a string

This is likely happening because you have some unmigrated components somewhere. If it encounters one of those, it errors and the importMap generation halts. This likely prevents the imports for your Logo / Icon graphics to be generated, as the import map generation halts before it reaches that point

Could you make sure everything is migrated?

[nlvogel]

@AlessioGr thanks for that! I commented out all of my custom descriptions until I can properly migrate/rebuild them and it solved my Logo / Icon issue.

[megetron3]

@nlvogel not sure how to add this custom component, can you send the changes you made?

[r1tsuu]

Would VScode / Typescript plugin for path auto-completion be worth it? I'm thinking of a function with some reserved keyword like importComponent. Then, the idea is to somehow via VSCode / TS API modify autosuggestions with available paths + named exports when calling this function. If we we'll get a luck to do that via TS, we can even prevent errors at the build time.

[janus-reith]

Upgrading my Project which contained a couple custom Fields and Cells worked fine without any major issues.

My main headache had been several duplicated definitions for nested Lexical Blocks inflating the bundle size a lot, these are finally gone 🥳

The initial HTML size is down by > 80% and the admin loads way faster.

I also have the impression that both navigation within the Admin and API responses became faster as well. I wonder if these recursed definitions could've had an effect on the API layer aswell or if I'm on the wrong track here, will need to take the time and measure some resonse times.

Overall I'm very happy these changes landed!

[janus-reith]

Only nitpick, the release notes contain a good summary of the required steps to upgrade, however leave out that payload generate:importmap needs to be run in order for the importMap to be filled. The release notes seem to suggest that this happens on the fly.

[denolfe]

Thank you for the feedback. It should be auto-generated each time. Looks like the first time may be failing for some. We've added this command to the release notes.

[revnelson]

It would be great if the logging was better for these errors. I'm also getting the css error referencing react-image-crop, but as far as I know I've commented out all custom components. I have a large project so it's quite possible there is one hiding somewhere, but I've done a workplace search for components: { and double checked the 30+ files and am now at a loss for what to try...

[revnelson]

Commenting out the components section of the Field config wasn't enough, I had to comment out the component import statement as well. It still should be considered necessary to log where the importMap generation halts for users to troubleshoot easier.

Unfortunately, I'm now getting a new error:

pnpm payload generate:importMap

> [email protected] payload /Users/revnelson/coding/next-payload
> cross-env NODE_OPTIONS=--no-deprecation payload "generate:importMap"

/Users/revnelson/coding/next-payload/node_modules/.pnpm/[email protected]/node_modules/server-only/index.js:1
throw new Error(
      ^

Error: This module cannot be imported from a Client Component module. It should only be used from a Server Component.
    at Object.<anonymous> (/Users/revnelson/coding/next-payload/node_modules/.pnpm/[email protected]/node_modules/server-only/index.js:1:7)
    at Module._compile (node:internal/modules/cjs/loader:1358:14)
    at Module._extensions..js (node:internal/modules/cjs/loader:1416:10)
    at Object.transformer [as .js] (file:///Users/revnelson/coding/next-payload/node_modules/.pnpm/[email protected]/node_modules/tsx/dist/register-B_eFQvfc.mjs:2:748)
    at Module.load (node:internal/modules/cjs/loader:1208:32)
    at Module._load (node:internal/modules/cjs/loader:1024:12)
    at cjsLoader (node:internal/modules/esm/translators:348:17)
    at ModuleWrap.<anonymous> (node:internal/modules/esm/translators:297:7)
    at ModuleJob.run (node:internal/modules/esm/module_job:222:25)
    at async ModuleLoader.import (node:internal/modules/esm/loader:316:24)

This is similarly vague as to where the error occurred as the only files I'm importing the server-only module is in server actions.

[AlessioGr]

I think the server-only package will not work outside of Next.js - I recommend not importing it in your config.

[lynndylanhurley]

After upgradiing from beta.78 -> beta.84 i'm getting the following error when trying to run any payload cli command:

❯ payload generate:importmap          
/Users/lynn/Code/ECF/ecf-web/apps/web/src/blocks/AccordionBlock/img/preview.png:1
�PNG


SyntaxError: Invalid or unexpected token
    at internalCompileFunction (node:internal/vm:77:18)
    at wrapSafe (node:internal/modules/cjs/loader:1288:20)
    at Module._compile (node:internal/modules/cjs/loader:1340:27)
    at Module._extensions..js (node:internal/modules/cjs/loader:1435:10)
    at Object.transformer [as .js] (file:///Users/lynn/Code/ECF/ecf-web/node_modules/.pnpm/[email protected]/node_modu
les/tsx/dist/register-B_eFQvfc.mjs:2:878)
    at Module.load (node:internal/modules/cjs/loader:1207:32)
    at Module._load (node:internal/modules/cjs/loader:1023:12)
    at Module.require (node:internal/modules/cjs/loader:1235:19)
    at require (node:internal/modules/helpers:176:18)
    at <anonymous> (/Users/lynn/Code/ECF/ecf-web/apps/web/src/blocks/AccordionBlock/AccordionBlock.config.ts:4:
21)

Node.js v21.4.0

In this case it's choking on the .png file that's processed with file-loader into a URL that's used for block preview images.

But even after I comment out all of the image imports, it fails while processing .css imports from dependencies.

Is this to be expected?

And if so, what is the workaround?

[AlessioGr]

This happens if client files like react components or png files are still imported somewhere in your config. This is not allowed anymore. You need to make sure to get rid of all of them before being able to run cli commands

[tyteen4a03]

I wanted to ask: Did the team consider the native import() syntax and why the team chose to use a path instead of a dynamic import() call that is resolved at runtime? I'm not knowledgeable in this subject so eager to learn.

[AlessioGr]

We considered it, but it didn't work. Even if dynamic imports are used, webpack will still attempts to bundle the components when the config is imported on the server. + the syntax for dynamic importing named exports is atrocious