---
title: "TypeScript Plugin (Experimental)"
aliases: [payload-ts-plugin, payloadcms-typescript-plugin, ts-language-service-plugin]
tags: [payloadcms, typescript, ide, dx, autocomplete, vscode]
sources: [raw/typescript__ts-plugin.md]
created: 2026-05-15
updated: 2026-05-15
---

# TypeScript Plugin (Experimental)

`@payloadcms/typescript-plugin` — optional TypeScript Language Service Plugin that enhances IDE experience for [[wiki/payloadcms/custom-components|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

```bash
pnpm add -D @payloadcms/typescript-plugin
```

Add to `tsconfig.json`:

```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).

1. `Cmd+Shift+P` → **"TypeScript: Select TypeScript Version"** → **"Use Workspace Version"**
2. `Cmd+Shift+P` → **"TypeScript: Restart TS Server"**

For teams — commit `.vscode/settings.json`:

```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:

```ts
// 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:

```json
{
  "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

## Related

- [[wiki/payloadcms/custom-components|Custom Components]] — the feature this plugin validates
- [[wiki/payloadcms/admin-panel-overview|Admin Panel Overview]] — where component slots are configured
- [[wiki/payloadcms/typescript|TypeScript in Payload]] — general TS setup and generated types

## Sources

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