https://github.com/x3m-industries/x3m-payload
Payload CMS libraries and utilities
https://github.com/x3m-industries/x3m-payload
fields payload payload-plugin payloadcms
Last synced: 5 months ago
JSON representation
Payload CMS libraries and utilities
- Host: GitHub
- URL: https://github.com/x3m-industries/x3m-payload
- Owner: x3m-industries
- License: mit
- Created: 2026-01-31T12:30:49.000Z (6 months ago)
- Default Branch: main
- Last Pushed: 2026-02-05T23:45:06.000Z (6 months ago)
- Last Synced: 2026-02-06T01:32:52.292Z (6 months ago)
- Topics: fields, payload, payload-plugin, payloadcms
- Language: TypeScript
- Homepage:
- Size: 454 KB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Codeowners: .github/CODEOWNERS
- Security: SECURITY.md
- Agents: AGENTS.md
Awesome Lists containing this project
README
# @x3m-industries/payload
[](https://opensource.org/licenses/MIT)
[](https://www.typescriptlang.org/)
[](https://payloadcms.com/)
**The missing pieces for Payload CMS.** Type-safe services, production-ready fields, zero boilerplate.
> [!TIP]
> **Built for Payload 3.0+ and Next.js App Router.**
> Fully compatible with the new server-only architecture.
_See the magic: Full TypeScript autocomplete for your entire backend logic._
---
## Why This Exists
Every Payload 3.0 project ends up with the same problems:
❌ **Unsafe API calls** — `payload.find({ collection: 'orders' })` is just a magic string.
❌ **Manual Validation** — Rewriting generic phone/VAT/address regexes for every client.
❌ **Scattered Logic** — Service methods spread across 'utilities' folders with no structure.
**This toolkit solves all three.** It brings the structure of NestJS to the flexibility of Payload.
---
## 🚀 Quick Start (Demo)
Want to see it in action? Run the local demo in 2 minutes.
```bash
# 1. Clone the repo
git clone https://github.com/x3m-industries/x3m-payload.git
cd x3m-payload
# 2. Install dependencies
yarn install
# 3. Start the demo
yarn demo
```
Open [http://localhost:3000](http://localhost:3000) to explore the admin UI and frontend.
---
## 🔌 Plugin Mode: The Game Changer
Define services directly on your collections. Access them from `payload.services`. Fully typed.
```typescript
// payload.config.ts
import { servicesPlugin } from '@x3m-industries/lib-services';
export default buildConfig({
plugins: [servicesPlugin()],
collections: [Orders, Customers],
globals: [Settings],
});
```
```typescript
// collections/Orders.ts
export const Orders = {
slug: 'orders' as const,
fields: [...],
service: {
extensions: ({ getPayload, collection }) => ({
async markShipped({ id }: { id: string }) {
const payload = await getPayload();
return payload.update({ collection, id, data: { status: 'shipped' } });
},
}),
cache: { findMany: { life: 'hours', tags: ['orders'] } }, // "use cache"
},
} satisfies CollectionConfig;
```
```typescript
// collections/Customers.ts
// Just standard CRUD? No problem.
export const Customers = {
slug: 'customers' as const,
fields: [...],
service: true, // Auto-enable default CRUD service
} satisfies CollectionConfig;
```
```typescript
// Anywhere in your app
import { getPayload } from './services'; // Centralized definition
const payload = await getPayload();
// Default CRUD — fully typed
await payload.services.orders.findMany({ where: { status: { equals: 'pending' } } });
await payload.services.orders.findOneById({ id: '123' });
// Custom methods — fully typed
await payload.services.orders.markShipped({ id: '123' });
// Dynamic access
await payload.services('orders').createOne({ data: {...} });
```
**No casting. No magic strings. Full autocomplete.**
---
## 🛡️ Production Fields, Out of the Box
Stop rewriting validation logic. These fields work correctly the first time.
```typescript
import { addressField, idField, phoneField, vatField } from '@x3m-industries/lib-fields';
export const Customers: CollectionConfig = {
slug: 'customers',
fields: [
idField({ config: { type: 'uuidv7' } }), // Auto-generated, prefixed IDs
phoneField({ overrides: { name: 'mobile' } }), // libphonenumber-js validation
vatField({ overrides: { name: 'vatNumber' } }), // EU VAT checksum validation
addressField(), // Complete address group
],
};
```
| Field | What It Does |
| -------------- | ------------------------------------------------------ |
| `idField` | Auto-generated IDs (uuid, uuidv7, nanoid, ulid, cuid2) |
| `phoneField` | International phone validation via libphonenumber-js |
| `vatField` | EU VAT validation with format + checksum |
| `addressField` | Street, city, state, zip, country — one line |
| `slugField` | Auto-generated slugs with localization + locking |
| `emailField` | Email validation with domain restrictions |
| `urlField` | URL validation with protocol enforcement |
| `countryField` | Pre-filled country select |
---
## 📦 Installation
```bash
# Fields
yarn add @x3m-industries/lib-fields
# Services
yarn add @x3m-industries/lib-services
```
---
## 📚 Documentation
Full API documentation in each package:
- **[lib-fields](./packages/lib-fields/README.md)** — Field configuration, validation options, customization
- **[lib-services](./packages/lib-services/README.md)** — Plugin setup, extensions, disable methods, type safety
---
## 🛠️ Development
```bash
yarn install # Install dependencies
yarn dev # Development mode
yarn validate # Build + lint + typecheck + test
```
---
## 📄 License
MIT © [X3M Industries](https://x3m.industries)