Payload CMS Integration Guide

Payload CMS is integrated into the Aruuri platform via the apps/web Next.js application, serving as a powerful, headless content management system. This integration allows for robust management of editorial content, media assets, and other administrative data, all while leveraging Aruuri's [Aruuri Monorepo Architecture] and [Database Architecture & Domain Separation]. This guide details its configuration, how it handles media, generates types, and operates within the Next.js serverless environment.

Configuration Overview (apps/web/src/payload.config.ts)

The core configuration for Payload CMS resides in apps/web/src/payload.config.ts. This file orchestrates how Payload connects to the database, manages files, and integrates with the overall application.

1. Database Connection to Content Domain

Payload CMS is configured to connect specifically to the Content Database domain. This adheres to Aruuri's domain-driven database separation strategy, ensuring that CMS-related data is isolated from other business domains like Platform, Projects, and Finance.

• Adapter: Payload utilizes the @payloadcms/db-postgres adapter for PostgreSQL.
• Connection String: The connectionString is dynamically sourced from environment variables: ARUURI_CONTENT_DATABASE_URL_POOLED (for pooled connections, preferred for serverless) or ARUURI_CONTENT_DATABASE_URL (for direct connections, e.g., migrations).
  • During the Next.js build phase (process.env.NEXT_PHASE?.includes('build')), a placeholder connection string is used to allow static generation without requiring a live database connection. This is crucial for optimizing build times and avoiding unnecessary database hits in CI/CD.
• Drizzle ORM: While Payload internally manages its data, the packages/database module also defines a contentDb client with contentSchema for direct, type-safe Drizzle ORM interactions with the content database, demonstrating how other parts of the application can interact with this domain.

2. S3 Storage for Media

Media file management is externalized to AWS S3, integrated with CloudFront for optimal performance and secure delivery. This is configured using the @payloadcms/storage-s3 plugin.

• S3 Bucket: The S3_UPLOAD_BUCKET environment variable specifies the S3 bucket where media files are stored. This bucket is created by the infrastructure as an sst.aws.Bucket with access: 'cloudfront', ensuring each deployment stage (e.g., production, dev, preview-pr-123) has its own isolated media bucket, as detailed in [Deployment & Ephemeral Preview Environments].
• CloudFront Integration (CLOUDFRONT_MEDIA_URL):
  • The cloudfrontMediaUrl is derived from the CLOUDFRONT_MEDIA_URL environment variable, which points to the CloudFront distribution domain name.
  • The generateFileURL function is overridden to construct public URLs for media assets using the CloudFront domain. This is vital for serving media efficiently and securely, and especially for maintaining access to assets even after ephemeral preview environments (and their S3 buckets) are deleted. Without this, assets uploaded in a preview-pr-XYZ environment would become inaccessible once that preview bucket is removed.
• AWS Credentials: Credentials for S3 operations are managed via the AWS Lambda execution role IAM permissions, eliminating the need to explicitly set sensitive credentials in environment variables.

3. Type Generation (apps/web/src/payload-types.ts)

Payload automatically generates TypeScript types based on its collections and globals.

• typescript.outputFile: The buildConfig option typescript: { outputFile: path.resolve(dirname, 'payload-types.ts') } ensures that Payload's internal schema is reflected in the apps/web/src/payload-types.ts file.
• Purpose: This generated file provides full type safety when interacting with Payload's API endpoints or data directly within the Next.js application, improving developer experience and reducing runtime errors. It defines interfaces for collections like User (Payload's internal admin users), Media, and other system collections (payload-locked-documents, payload-preferences, payload-migrations).

4. Admin Interface & Editor

• admin.user: Configured to use the Users.slug collection for administrative users, providing a custom user authentication and management system for the CMS.
• editor: Leverages the lexicalEditor() for a modern and flexible rich-text editing experience within the Payload admin UI.
• sharp: The sharp library is specified for image processing, allowing Payload to handle image transformations (resizing, optimization) efficiently. It is externalized in next.config.ts for proper bundling in the AWS Lambda environment.

Key Collections

Payload is configured with two primary collections within apps/web/src/payload.config.ts (though more content-specific collections like Posts, Pages, Categories are defined in packages/database/src/schema/content.ts):

• Users: This collection (defined internally in Payload as users) manages the administrative users who can log into the Payload CMS backend. These are distinct from the platform's public users, which are managed in the platform database domain.
• Media: This collection is responsible for handling all uploaded files (images, documents, etc.). It integrates directly with the S3 storage and CloudFront CDN setup described above, storing metadata (alt text, filename, mimeType, dimensions) and the CloudFront URL.

Interaction with Next.js App and Serverless Environment

Payload CMS runs as part of the apps/web Next.js application, which is deployed as a serverless application using SST v3 on AWS Lambda (OpenNext).

• next.config.ts: The serverExternalPackages array in apps/web/next.config.ts is crucial. It ensures that sharp and @payloadcms/db-postgres are externalized during the Next.js build process. This prevents bundling issues and allows the AWS Lambda runtime to correctly use pre-compiled binaries for these dependencies, especially sharp for image processing.
• open-next.config.ts: Specifically configures the sharp package for Lambda's x64 architecture and glibc libc, ensuring compatibility within the serverless environment for image optimization functions.
• src/middleware.ts: During early development, all environments (including Payload's admin interface) are protected by a password-based login form, enforced by a Next.js middleware. This temporary measure requires the SITE_PASSWORD environment variable to be set. This ensures only authorized access during the MVP phase.
• Serverless Deployment: The entire apps/web application, including the Payload CMS endpoints and admin UI, is deployed as an sst.aws.Nextjs construct. This means Payload's server-side logic runs within AWS Lambda functions, benefiting from serverless scalability and cost-efficiency. Its database connections are optimized for this environment using pooled connections (Neon's HTTP driver).

By carefully integrating Payload CMS within the Next.js monorepo and leveraging AWS serverless capabilities, Aruuri provides a flexible and scalable solution for content management that aligns with its transparent and impact-driven mission.