TypeScript Plugin (Experimental)

Payload ships an optional TypeScript Language Service Plugin (@payloadcms/typescript-plugin) that enhances your IDE experience when working with Custom Components. It understands Payload's PayloadComponent import path conventions and provides:

• Path validation — red squigglies when a component path doesn't resolve to a real file
• Export validation — errors when the named export doesn't exist in the target module, with "Did you mean?" suggestions
• Autocomplete — file and directory suggestions while typing the path, and export name suggestions after #
• Go-to-definition — Ctrl/Cmd+click on a component path string to jump to the component's source

Install the plugin as a dev dependency:

Then add it to the plugins array in your tsconfig.json:

TypeScript language service plugins only load when the editor uses the workspace version of TypeScript (the one installed in your project's node_modules). By default, VS Code uses its own bundled version which won't load the plugin.

To switch: open the command palette (Cmd+Shift+P) and run "TypeScript: Select TypeScript Version", then choose "Use Workspace Version".

For teams, add the following to .vscode/settings.json so everyone is prompted to switch:

After selecting the workspace version, restart the TypeScript server (Cmd+Shift+P → "TypeScript: Restart TS Server").

The plugin supports all of Payload's component path formats:

Both the string form and the object form are supported:

The plugin automatically detects baseDir by walking up from the current file to find the nearest payload.config.ts. Absolute paths (starting with /) and relative paths (starting with ./) are resolved relative to this directory.

If your project uses a non-standard layout, you can override baseDir in the plugin config:

The baseDir path is relative to the tsconfig.json location.

The plugin detects PayloadComponent positions by checking the contextual type of string literals in your config. Any string typed as PayloadComponent, CustomComponent, or any type that resolves to the same false | RawPayloadComponent | string union shape is automatically validated.

This means the plugin works everywhere Payload expects a component path — collection field components, global components, admin panel components, dashboard widgets, and custom views — without needing to hardcode specific config positions.