Registry / cms / payload-rest-client

payload-rest-client

library3.0.5jsnpmunverified

A typesafe REST API client for Payload CMS (current stable version 3.0.5, actively maintained). It provides a fully typed interface for all Payload CMS REST endpoints, including collections, globals, and custom endpoints. The client leverages TypeScript generics to enforce correct parameters, query options, and response types based on your Payload config. Key differentiators: first-class locale support, built-in auth methods (login, logout, refresh, unlock), and a type-safe custom endpoint system. Unlike generic fetch wrappers, it automatically types collection methods (find, create, update, delete) with your actual content types. Requires Payload CMS v2+.

cms integration

npm install payload-rest-client

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · PAYLOAD-REST-CLIEN

payload-rest-client

cmsjavascriptv3.0.5

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

createClient

✓ import { createClient } from 'payload-rest-client'

✗ const createClient = require('payload-rest-client')

Package is ESM-only, no CJS support. TypeScript users should use named import.

CustomEndpoint

✓ import { CustomEndpoint } from 'payload-rest-client'

✗ import { CustomEndpoint } from 'payload-rest-client/dist/customEndpoint'

Use top-level import, not internal path. CustomEndpoint is a type used for defining custom endpoints.

ClientConfig

✓ import type { ClientConfig } from 'payload-rest-client'

Only available as type import. Not exported as value.

Shows how to create a typed client, authenticate, and fetch a paginated list of posts with locale and sorting.

import { createClient } from 'payload-rest-client'; // Assume you have generated Payload types in './payload-types.ts' interface Post { id: string; title: string; content: string; createdAt: string; updatedAt: string; } interface Config { collections: { posts: Post; users: { id: string; email: string }; }; globals: {}; } type Locales = 'en' | 'de'; const client = createClient<Config, Locales>({ apiUrl: 'http://localhost:4000/api', cache: 'no-store', }); async function main() { const loginResult = await client.collections.users.login({ email: process.env.PAYLOAD_EMAIL ?? '', password: process.env.PAYLOAD_PASSWORD ?? '', }); const authClient = createClient<Config, Locales>({ apiUrl: 'http://localhost:4000/api', headers: { Authorization: `Bearer ${loginResult.token}` }, }); const posts = await authClient.collections.posts.find({ sort: '-title', locale: 'en', limit: 10, page: 1, }); console.log(posts.docs); } main();

Debug

Known issues

gotchaThe generic parameter must match your Payload config exactly. Mismatched types will cause runtime errors that TypeScript cannot catch.

fix

Ensure the Config type you pass to createClient matches the generated 'payload-types.ts' from Payload CMS. Use the exact type from your config export.

affects: >=1.0

gotchaLocale generic parameter must be a union of string literals, not a string type. Otherwise locale constraints are lost.

fix

Define locale type as e.g. 'en' | 'de' instead of string when creating client.

affects: >=1.0

breakingVersion 3.0.0 removed the old 'payloadRestClient' named export in favor of 'createClient'. Existing imports will break.

fix

Replace 'import { payloadRestClient } from "payload-rest-client"' with 'import { createClient } from "payload-rest-client"'.

affects: >=3.0.0

gotchaCustom endpoints defined in createClient options must have 'method' and 'path' properties. Missing path will cause a runtime error.

fix

Always provide both method and path for each custom endpoint. Path can be a string or a function returning a string.

affects: >=1.0

Errors

Common errors & fixes

Error: Cannot find module 'payload-rest-client'

Package not installed or ESM/CJS mismatch.

fix

Run 'npm install payload-rest-client' and ensure your project uses ESM ("type": "module" in package.json) or a bundler that supports ESM.

TypeError: client.collections.posts.find is not a function

Client created without proper Config or collections not recognized by the client.

fix

Ensure your Config type includes the collections object with expected keys (e.g., 'posts'). Check that createClient receives correct generic parameters.

Property 'token' does not exist on type 'LoginResult<T>'

LoginResult type may differ between versions or Payload config does not have auth enabled for the users collection.

fix

Verify Payload config has auth enabled on users (auth: true). Check that your Config type matches the actual collection schema.

Upgrade

Version history

3.0.5latest on npm

Audit

Dependencies

payloadoptionalNeeded for generating Config type and understanding Payload CMS REST API structure

Agent activity

37 hits · last 30 days

node

Resources

githubhttps://github.com/dkirchhof/payload-rest-client ↗

packagepayload-rest-client ↗

homepagehttps://github.com/dkirchhof/payload-rest-client ↗