|
1 | | -# bun starter |
| 1 | +# Payload Express Middleware |
2 | 2 |
|
3 | | -## Getting Started |
| 3 | +`payload-express-middleware` is a library that enables API routing in Express.js, similar to Next.js API routes, using [Payload CMS](https://payloadcms.com). This middleware simplifies the process of integrating Payload's Local API with an Express.js application. |
4 | 4 |
|
5 | | -Click the [Use this template](https://github.com/wobsoriano/bun-lib-starter/generate) button to create a new repository with the contents starter. |
| 5 | +## Features |
6 | 6 |
|
7 | | -OR |
| 7 | +- Seamlessly map API routes to Payload CMS collections. |
| 8 | +- Built-in authentication and authorization middleware. |
| 9 | +- CRUD operations for Payload collections. |
| 10 | +- Error handling for common Payload validation and authentication errors. |
8 | 11 |
|
9 | | -Run `bun create wobsoriano/bun-lib-starter ./my-lib`. |
| 12 | +## Installation |
10 | 13 |
|
11 | | -## Setup |
| 14 | +Install the library and its peer dependencies: |
12 | 15 |
|
| 16 | +NPM |
13 | 17 | ```bash |
14 | | -# install dependencies |
15 | | -bun install |
| 18 | +npm install payload-express-middleware payload express |
| 19 | +``` |
| 20 | + |
| 21 | +Yarn |
| 22 | +```bash |
| 23 | +yarn add payload-express-middleware payload express |
| 24 | +``` |
| 25 | + |
| 26 | +## Usage |
| 27 | + |
| 28 | +### 1. Initialize Payload CMS |
| 29 | + |
| 30 | +Ensure you have a Payload CMS configuration file (e.g., `payload.config.js`) and initialize Payload in your Express app. |
| 31 | + |
| 32 | +### 2. Use the Middleware |
| 33 | + |
| 34 | +Import and use the `payloadAPIRouterMiddleware` function in your Express app: |
| 35 | + |
| 36 | +```typescript |
| 37 | +import express from 'express'; |
| 38 | +import payload from 'payload'; |
| 39 | +import { payloadAPIRouterMiddleware } from 'payload-express-middleware'; |
| 40 | +import path from 'path'; |
| 41 | + |
| 42 | +const app = express(); |
| 43 | + |
| 44 | +async function start() { |
| 45 | + // Load Payload configuration |
| 46 | + const config = path.resolve(__dirname, '/route/to/payload.config.js'); |
| 47 | + |
| 48 | + // Initialize Payload |
| 49 | + await payload.init({ |
| 50 | + secret: 'PAYLOAD_SECRET', // Replace with your Payload secret |
| 51 | + config, |
| 52 | + }); |
| 53 | + |
| 54 | + // Use the middleware |
| 55 | + app.use(payloadAPIRouterMiddleware(payload)); |
| 56 | + |
| 57 | + // Use your other middleware, routes, etc |
| 58 | + // .... |
| 59 | + |
| 60 | + // Start the server |
| 61 | + app.listen(4000, () => { |
| 62 | + console.log('Express API running on port 4000'); |
| 63 | + }); |
| 64 | +} |
16 | 65 |
|
17 | | -# test the app |
18 | | -bun test |
| 66 | +start(); |
| 67 | +``` |
| 68 | + |
| 69 | +### 3. API Routes |
| 70 | + |
| 71 | +The middleware automatically maps the following routes to Payload's Local API: |
| 72 | + |
| 73 | +#### Authentication Routes |
| 74 | +- **Login**: `POST /api/users-collection}/login` |
| 75 | +- **Logout**: `POST /api/{users-collection}/logout` |
| 76 | +- **Me**: `GET /api/{users-collection}/me` |
| 77 | + |
| 78 | +Note: `{user-collection}` defined by your `payload.config.js` |
| 79 | + |
| 80 | +#### CRUD Routes |
| 81 | + |
| 82 | +- **Find Many**: `GET /api/:collection` |
| 83 | +- **Find By ID**: `GET /api/:collection/:id` |
| 84 | +- **Create**: `POST /api/:collection` |
| 85 | +- **Update**: `PATCH /api/:collection/:id` |
| 86 | +- **Delete**: `DELETE /api/:collection/:id` |
| 87 | + |
| 88 | +### 4. Example Payload Configuration |
19 | 89 |
|
20 | | -# build the app, available under dist |
21 | | -bun run build |
| 90 | +Ensure your Payload CMS configuration file (`payload.config.js`) is properly set up. For example: |
| 91 | + |
| 92 | +```javascript |
| 93 | +module.exports = { |
| 94 | + secret: 'MY_SECRET', |
| 95 | + collections: [ |
| 96 | + { |
| 97 | + slug: 'users', |
| 98 | + admin: true, // --> enables 'user-collection' for Auth operations |
| 99 | + fields: [ |
| 100 | + { name: 'email', type: 'email', required: true }, |
| 101 | + { name: 'password', type: 'password', required: true }, |
| 102 | + ], |
| 103 | + }, |
| 104 | + { |
| 105 | + slug: 'posts', |
| 106 | + fields: [ |
| 107 | + { name: 'title', type: 'text', required: true }, |
| 108 | + { name: 'content', type: 'richText' }, |
| 109 | + ], |
| 110 | + }, |
| 111 | + ], |
| 112 | +}; |
22 | 113 | ``` |
23 | 114 |
|
| 115 | +## API Documentation |
| 116 | + |
| 117 | +### `payloadAPIRouterMiddleware(payload: Payload)` |
| 118 | + |
| 119 | +This function creates an Express router that maps API routes to Payload's Local API. |
| 120 | + |
| 121 | +#### Parameters |
| 122 | +- `payload`: The initialized Payload CMS instance. |
| 123 | + |
| 124 | + |
| 125 | +## Error Handling |
| 126 | + |
| 127 | +The middleware includes built-in error handling for: |
| 128 | +- Validation errors (`400 Bad Request`). |
| 129 | +- Authentication errors (`401 Unauthorized`). |
| 130 | +- Not found errors (`404 Not Found`). |
| 131 | +- Generic server errors (`500 Internal Server Error`). |
| 132 | + |
24 | 133 | ## License |
25 | 134 |
|
26 | | -MIT |
| 135 | +This project is licensed under the [MIT License](LICENSE). |
0 commit comments