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

Installation

Install the plugin as a dev dependency:

1pnpm add -D @payloadcms/typescript-plugin

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

1{
2  "compilerOptions": {
3    "plugins": [{ "name": "next" }, { "name": "@payloadcms/typescript-plugin" }]
4  }
5}

VS Code / Cursor Setup

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:

1{
2  "js/ts.tsdk.path": "node_modules/typescript/lib",
3  "js/ts.tsdk.promptToUseWorkspaceVersion": true
4}

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

Supported Path Conventions

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

Format	Example	Resolution
Absolute (from baseDir)	`'/components/MyField#MyField'`	Resolved relative to `baseDir`
Relative	`'./components/MyField#MyField'`	Resolved relative to `baseDir`
tsconfig alias	`'@/components/MyField#MyField'`	Resolved via tsconfig `paths`
Package import	`'@payloadcms/ui/rsc#MyComponent'`	Resolved via node_modules
Default export	`'/components/MyField'`	Uses `default` export

Both the string form and the object form are supported:

1// String form
2{
3  admin: {
4    components: {
5      Field: '/components/MyField#MyField',
6    }
7  }
8}
9
10// Object form
11{
12  admin: {
13    components: {
14      Field: {
15        path: '/components/MyField',
16        exportName: 'MyField',
17      }
18    }
19  }
20}

Configuration

Base Directory

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:

1{
"compilerOptions": {
  "plugins": [
    {
      "name": "@payloadcms/typescript-plugin",
      "baseDir": "./src"
    }
  ]
}
10}

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

How It Works

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.

Was this page helpful?

See what others are building with Payload.

"Payload has transformed the way our clients manage content. It's an indispensable tool for any modern agency."

Get the resources you need to start building today

Microsoft chose Payload to tell the world about AI.