TypeScript Plugin (Experimental)

@payloadcms/typescript-plugin — optional TypeScript Language Service Plugin that enhances IDE experience for wiki/payloadcms/custom-components with path-aware validation and autocomplete.

Experimental — may change in future releases. Does not affect tsc compilation or build output — IDE only.

Features

Path validation — red squigglies when a PayloadComponent path doesn't resolve to a real file
Export validation — errors when the named export (after #) doesn't exist; offers "Did you mean?" suggestions
Autocomplete — file/directory suggestions while typing; export name suggestions after #
Go-to-definition — Ctrl/Cmd+click on a component path string jumps to the source

Installation

pnpm add -D @payloadcms/typescript-plugin

Add to tsconfig.json:

{
  "compilerOptions": {
    "plugins": [
      { "name": "next" },
      { "name": "@payloadcms/typescript-plugin" }
    ]
  }
}

VS Code / Cursor Setup

Language service plugins only load when the editor uses the workspace TypeScript (not the bundled VS Code version).

Cmd+Shift+P → "TypeScript: Select TypeScript Version" → "Use Workspace Version"
Cmd+Shift+P → "TypeScript: Restart TS Server"

For teams — commit .vscode/settings.json:

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

Supported Path Formats

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

Both string form and object form are supported:

// String form
Field: '/components/MyField#MyField'

// Object form
Field: { path: '/components/MyField', exportName: 'MyField' }

Configuration

Base Directory

Plugin auto-detects baseDir by walking up from the current file to find payload.config.ts. Override if needed:

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

baseDir is relative to tsconfig.json location.

How It Works

Detects PayloadComponent positions by checking the contextual type of string literals. Any string typed as PayloadComponent, CustomComponent, or the false | RawPayloadComponent | string union is automatically validated — no hardcoded config positions needed.

Covers: collection field components, global components, admin panel components, dashboard widgets, custom views.

Key Takeaways

Install as dev dependency only — no runtime impact, IDE only
Must switch VS Code to workspace TypeScript or the plugin won't load
Supports all Payload path formats: absolute, relative, tsconfig alias, package import, default export
Auto-detects baseDir from payload.config.ts; override with "baseDir": "./src" for monorepos
Works anywhere PayloadComponent type is used — no config-position hardcoding

wiki/payloadcms/custom-components — the feature this plugin validates
wiki/payloadcms/admin-panel-overview — where component slots are configured
wiki/payloadcms/typescript — general TS setup and generated types

Sources

raw/typescript__ts-plugin.md
https://payloadcms.com/docs/typescript/ts-plugin

4 KiB Raw Permalink Blame History