Skip to content

README.md

Latest commit

 

History

History
142 lines (100 loc) · 3.67 KB

README.md

File metadata and controls

142 lines (100 loc) · 3.67 KB

Payload Express Middleware

payload-express-middleware is a library that enables API routing in Express.js, similar to Next.js API routes, using Payload CMS. This middleware simplifies the process of integrating Payload's Local API with an Express.js application.

Features

  • Seamlessly map API routes to Payload CMS collections.
  • Built-in authentication and authorization middleware.
  • CRUD operations for Payload collections.
  • Error handling for common Payload validation and authentication errors.

Installation

Install the library and its peer dependencies:

NPM

npm install payload-express-middleware payload express

Yarn

yarn add payload-express-middleware payload express

Usage

1. Initialize Payload CMS

Ensure you have a Payload CMS configuration file (e.g., payload.config.js) and initialize Payload in your Express app.

2. Use the Middleware

Import and use the payloadAPIRouterMiddleware function in your Express app:

import express from "express";
import payload from "payload";
import { payloadAPIRouterMiddleware } from "payload-express-middleware";
import path from "path";

const app = express();

async function start() {
  // Load Payload configuration
  const config = path.resolve(__dirname, "/route/to/payload.config.js");

  // Initialize Payload
  await payload.init({
    secret: "PAYLOAD_SECRET", // Replace with your Payload secret
    config,
  });

  // Use the middleware
  app.use(payloadAPIRouterMiddleware(payload, options)); // options are Optional

  // Use your other middleware, routes, etc
  // ....

  // Start the server
  app.listen(4000, () => {
    console.log("Express API running on port 4000");
  });
}

start();

3. API Routes

The middleware automatically maps the following routes to Payload's Local API:

Authentication Routes

  • Login: POST /api/users-collection}/login
  • Logout: POST /api/{users-collection}/logout
  • Me: GET /api/{users-collection}/me

Note: {user-collection} defined by your payload.config.js

CRUD Routes

  • Find Many: GET /api/:collection
  • Count: POST /api/:collection/count
  • Find By ID: GET /api/:collection/:id
  • Create: POST /api/:collection
  • Update: PATCH /api/:collection/:id
  • Delete: DELETE /api/:collection/:id

4. Example Payload Configuration

Ensure your Payload CMS configuration file (payload.config.js) is properly set up. For example:

module.exports = {
  secret: "MY_SECRET",
  collections: [
    {
      slug: "users",
      admin: true, // --> enables 'user-collection' for Auth operations
      fields: [
        { name: "email", type: "email", required: true },
        { name: "password", type: "password", required: true },
      ],
    },
    {
      slug: "posts",
      fields: [
        { name: "title", type: "text", required: true },
        { name: "content", type: "richText" },
      ],
    },
  ],
};

API Documentation

payloadAPIRouterMiddleware(payload: Payload, options?: PayloadAPIRouterMiddlewareOptions)

This function creates an Express router that maps API routes to Payload's Local API.

Parameters

  • payload: The initialized Payload CMS instance.
  • options: Additional options to the middleware:
    • simpleResponses?: boolean - if set to true return response.docs as the whole response

Error Handling

The middleware includes built-in error handling for:

  • Validation errors (400 Bad Request).
  • Authentication errors (401 Unauthorized).
  • Not found errors (404 Not Found).
  • Generic server errors (500 Internal Server Error).

License

This project is licensed under the MIT License.