Using getPayload in a Separate Next.js Project with Full Type Safety in NX Monorepo

[BetterLuke]

Hi PayloadCMS community,

I'm working on an NX monorepo with two projects: app-backend (a PayloadCMS instance) and app-frontend (a Next.js app). I want app-frontend to use getPayload to create a fully typed Payload instance for direct database access (Local API), ensuring type hints for the collection field (e.g., 'banner' | 'users' | 'media') and query results (e.g., Banner[]), while avoiding dependencies like sharp. Here's my setup and issue.

Setup

Monorepo Structure

/nx-monorepo
├── packages/
│   ├── app-backend/
│   │   ├── src/
│   │   │   ├── collections/
│   │   │   │   ├── Banner.ts
│   │   │   │   ├── Users.ts
│   │   │   │   ├── Media.ts
│   │   │   ├── payload.config.ts
│   │   │   ├── payload-types.ts
│   │   ├── package.json
│   ├── app-frontend/
│   │   ├── src/
│   │   ├── package.json
├── nx.json
├── package.json

app-backend Configuration

// packages/app-backend/payload.config.ts
import { buildConfig } from 'payload';
import { mongooseAdapter } from '@payloadcms/db-mongodb';
import path from 'path';
import { fileURLToPath } from 'url';
import { Users, Media, Banner } from './collections';

const filename = fileURLToPath(import.meta.url);
const dirname = path.dirname(filename);

export default buildConfig({
  collections: [Users, Media, Banner],
  db: mongooseAdapter({ url: process.env.DATABASE_URI || '' }),
  secret: process.env.PAYLOAD_SECRET || '',
  typescript: { outputFile: path.resolve(dirname, 'payload-types.ts') },
  // Other configs like sharp, s3Storage omitted
});

Issue

When importing app-backend's config into app-frontend and using getPayload, the collection field in payload.find lacks type hints (typed as string instead of 'banner' | 'users' | 'media'):

// packages/app-frontend/src/lib/queryBannerBySlug.ts
import { getPayload } from 'payload';
import configPromise from '@my-monorepo/app-backend';
import type { Banner } from '@my-monorepo/app-backend/types';

export const queryBannerBySlug = async ({ slug }: { slug: string }) => {
  const payload = await getPayload({ config: await configPromise });
  const result = await payload.find({
    collection: 'banner', // No type hints
    limit: 1,
    where: { slug: { equals: slug } },
  }) as { docs: Banner[] };
  return result;
};

Proposed Solution

To achieve type safety, I created a minimal payload.config.ts in app-frontend, reusing app-backend's collections:

// packages/app-frontend/src/payload.config.ts
import { buildConfig } from 'payload';
import { mongooseAdapter } from '@payloadcms/db-mongodb';
import path from 'path';
import { fileURLToPath } from 'url';
import { Banner, Users, Media } from '@my-monorepo/app-backend/collections';

const filename = fileURLToPath(import.meta.url);
const dirname = path.dirname(filename);

export default buildConfig({
  collections: [Users, Media, Banner],
  db: mongooseAdapter({ url: process.env.DATABASE_URI || '' }),
  secret: process.env.PAYLOAD_SECRET || '',
  typescript: { outputFile: path.resolve(dirname, 'payload-types.ts') },
});

// packages/app-frontend/src/lib/payload-client.ts
import payload from 'payload';
import config from '../payload.config';

let payloadInstance: typeof payload | null = null;

export const getPayloadClient = async () => {
  if (payloadInstance) return payloadInstance;
  payloadInstance = await payload.init({ config, local: true });
  return payloadInstance;
};

// packages/app-frontend/src/lib/queryBannerBySlug.ts
import { getPayloadClient } from './payload-client';
import type { Banner } from './payload-types';

export const queryBannerBySlug = async ({ slug }: { slug: string }) => {
  const { isEnabled: draft } = await draftMode();
  const payload = await getPayloadClient();
  const result = await payload.find({
    collection: 'banner', // Type hints: 'banner' | 'users' | 'media'
    limit: 1,
    draft,
    pagination: false,
    overrideAccess: draft,
    where: { slug: { equals: slug } },
  }) as { docs: Banner[] };
  return result;
};

Dependencies

// packages/app-frontend/package.json
{
  "dependencies": {
    "payload": "^2.0.0",
    "@payloadcms/db-mongodb": "^1.0.0",
    "@my-monorepo/app-backend": "workspace:*"
  }
}

Type Sync

pnpm --filter @my-monorepo/app-backend generate:types
cp packages/app-backend/payload-types.ts packages/app-frontend/src/

Questions

1. Is the minimal payload.config.ts in app-frontend the best approach to ensure type safety for collection and query results while avoiding dependencies like sharp?
2. Can I directly use app-backend's config with getPayload and retain type hints without a local config? If so, how?
3. Any NX-specific tips for sharing collections and types between projects to streamline this setup?

This solution works, but I’d love feedback on optimizing type safety or configuration sharing in NX. Thanks!

[anyuj]

Not really familiar with the NX, but there is a sample repo for Turborepo. Hopefully it helps https://github.com/fusionary/turbo-payload