A Deep Dive into Payload CMS's Code-First Configuration

Payload CMS is celebrated for its beautiful, intuitive admin interface. It’s clean, fast, and makes content management a breeze. But the true superpower of Payload—the feature that sets it apart in the crowded headless CMS market—lies beneath the surface: its code-first configuration.

While many CMS platforms force you into a click-and-configure workflow within a GUI, Payload empowers you to define your entire data schema, access control, and business logic directly in TypeScript. This approach transforms your CMS from a rigid box into a version-controlled, fully extensible part of your application's codebase.

At studio.do, we let you harness this power instantly. We handle the deployment, hosting, and custom branding, so you can focus on what matters: crafting the perfect content engine with code.

Let's dive into why this code-first philosophy is a game-changer and how you can use it to build robust, scalable backends.

Why Code-First is a Developer's Dream

Before we get into the code, let's understand the "why." Defining your CMS in code offers several massive advantages:

• True Version Control: Your entire CMS schema lives in Git. You can track every change, review pull requests for schema modifications, revert to previous versions, and maintain a single source of truth. No more guessing who changed a field in the admin UI!
• Unmatched Flexibility: You are not limited by the options in a dropdown menu. Need a complex, conditional validation rule? Write a function. Want to fetch data from a third-party API when a field is updated? Use a hook. The only limit is what you can write in TypeScript.
• Superior Developer Experience (DX): Work in your favorite IDE with all the benefits of TypeScript, including autocompletion and static type-checking. This catches errors early, improves code quality, and makes collaboration seamless.
• Scalability and Testability: Code-based schemas are inherently more maintainable and testable. You can write unit tests for your access control logic, your custom hooks, and your validation functions, ensuring your CMS is as robust as the rest of your application.

The Heart of Your Project: payload.config.ts

Every Payload project is anchored by a central configuration file, typically payload.config.ts. This is where the magic happens. Here, you define your collections, global settings, user types, and more.

Let's start by building a simple Posts collection.

Defining a Collection

A Collection is a schema for a group of documents, like blog posts, products, or pages. Here’s a basic example:

// payload.config.ts
import { buildConfig } from 'payload/config';
import { Posts } from './collections/Posts'; // We'll define this next

export default buildConfig({
  // ... other config
  collections: [
    Posts,
    // Other collections like Users, Media, etc.
  ],
});

// collections/Posts.ts
import { CollectionConfig } from 'payload/types';

export const Posts: CollectionConfig = {
  slug: 'posts',
  admin: {
    useAsTitle: 'title',
    description: 'A collection for blog posts.',
  },
  fields: [
    {
      name: 'title',
      type: 'text',
      required: true,
    },
    {
      name: 'content',
      type: 'richText',
      required: true,
    },
    {
      name: 'status',
      type: 'select',
      options: [
        { label: 'Draft', value: 'draft' },
        { label: 'Published', value: 'published' },
      ],
      defaultValue: 'draft',
      admin: {
        position: 'sidebar',
      }
    }
  ],
};

In this example, we've defined a Posts collection with a title, content, and status. Notice how easy it is to set fields as required, provide options for a select dropdown, and even configure the layout of the admin panel (position: 'sidebar').

Power at Your Fingertips: Access Control

This is where code-first truly shines. Instead of simple role-based checkboxes, Payload uses function-based access control. You write functions that return true (access granted) or a query constraint to filter documents.

Let's secure our Posts collection:

// collections/Posts.ts
import { CollectionConfig } from 'payload/types';
import { User } from 'payload/generated-types';

const canModifyPost = ({ req: { user } }: { req: { user: User } }) => {
  // Admins can do anything
  if (user?.roles?.includes('admin')) {
    return true;
  }

  // Authors can modify their own posts
  // This returns a query constraint
  return {
    author: {
      equals: user.id,
    },
  };
};

export const Posts: CollectionConfig = {
  slug: 'posts',
  // ... other config from above
  access: {
    // Anyone can read published posts
    read: ({ req: { user } }) => {
      // Logged-in users can see drafts, everyone else sees published
      if (user) return true;
      return { status: { equals: 'published' } };
    },
    // Only logged-in users can create posts
    create: ({ req: { user } }) => !!user,
    // Admins can update any post, authors can only update their own
    update: canModifyPost,
    // Admins can delete any post, authors can only delete their own
    delete: canModifyPost,
  },
  fields: [
    // ... fields from above
    {
      name: 'author',
      type: 'relationship',
      relationTo: 'users',
      required: true,
      // Hide from the API, set automatically
      access: {
        create: () => false,
        update: () => false,
      },
      admin: {
        readOnly: true,
        position: 'sidebar',
      }
    },
  ],
  // ...
};

This is incredibly powerful. We've just implemented fine-grained, row-level security:

1. Anyone on the internet can read published posts.
2. Logged-in users can also see draft posts.
3. Only logged-in users can create a post.
4. Users can only update or delete posts they are the author of, unless they are an admin.

This level of granular control is simple to write and reason about in code but often impossible to achieve in a GUI-based system.

Focus on Code, Not Infrastructure with studio.do

You've seen the power and flexibility that Payload's code-first configuration provides. Now, imagine offering this to every one of your clients, fully branded with their logo and colors, without ever touching a server, configuring a database, or setting up a deployment pipeline.

That's the studio.do promise.

You write the payload.config.ts that defines the perfect, bespoke CMS for your client's needs. Then, you make a single API call to studio.do.

import { studio } from '@do-sdk/js';

// Deploy a new white-labeled Payload CMS instance
const newSite = await studio.deploy({
  projectName: 'acme-corp-blog',
  brand: {
    name: 'ACME Corp',
    logoUrl: 'https://cdn.acme.com/logo.svg',
    colors: {
      primary: '#1E40AF',
      secondary: '#F3F4F6'
    }
  },
  database: {
    provider: 'mongodb',
    connectionString: process.env.MONGO_DB_URL
  }
});

console.log('CMS deployed:', newSite.adminUrl);

We instantly provision, deploy, and host your Payload instance as a service, complete with your client's branding. You focus on creating value with code; we handle the rest.

Conclusion

Payload's code-first configuration is more than just a feature—it's a paradigm shift that gives developers the control, flexibility, and power they need to build truly modern content solutions. By embracing code as the source of truth, you can create systems that are version-controlled, highly customizable, and infinitely scalable.

Ready to leverage the full power of Payload without the overhead of infrastructure management? Explore studio.do and deploy your first custom-branded CMS in minutes.