All you need to know about Payload CMS configurations
In this guide, we’re going to go work on extending the Payload CMS config file.
In my last guide, we got started with the
Payload by its design is config-based and code-first. This means that you will need to manually add much of the functionality you would like Payload CMS to have. While that sounds like a hassle if you’re in a rush, the level of flexibility this allows you to have over your CMS flow is unparalleled.
The config can feel deep and daunting, but interacting with your configuration will be simple and intuitive.
If you don’t already have a Payload project set up, go back to my “Getting Started with PayloadCMS” and “Getting Started with MongoDB for PayloadCMS” guides and read those before continuing on with this guide.
There are many options available to you in the Payload config. For the sake of this guide, we’ll only walk through a couple of them.
The first is the admin option. This allows you to configure options for your main admin panel. Here you can set things like the collection you’d like to use to allow users to login, select a default date format, define custom components, add metadata, and even disable the entire admin panel if you wanted to.
Let’s take a look at a few of these options, starting with the user option. This is the field that you can use to indicate which collection you want people to login from. This comes in handy when you want a separate people-type collection like “author” but you want to keep authors separate from admin users. In order for this to work, you should set “auth: true” in the Collection with which you would like to enable authentication. There’s not much to expand on here in this field, but when we talk about access control later, you can set different permissions at the user level to gain even more control over how people access the admin panel.
You can also select a default date format using any valid date-fns format patter. So, for example, if you want to change from the default PayloadCMS date format, you can define the “dateFormat” option as something like “MM/dd/yyyy” to change how the date is rendered within your PayloadCMS Admin Panel. This comes in handy if you want a fully custom way to represent dates or you want to handle a date differently than PayloadCMS does. People all handle dates differently, so it’s nice to have the flexibility here.
The next config option we’ll talk about is the editor. This is how you set your default RichText editor. PayloadCMS prefers Lexical editor for new projects, but you can also choose Slate if you’d like to. Keep in mind you will need to import either editor from Payload in order to define your default editor. Here’s how you set that up.
DB is a required field and can be MongoDB, Postgres, or SQLite. You will need to import whichever adapter you would like to use in order to define the database your project will use. You should also put the database connection string in an environment variable to protect it. Watch my “Getting Started With MongoDB for PayloadCMS” to see how to set up your own hosted database.
Choose whichever database you feel comfortable with using, but I typically default to MongoDB for PayloadCMS projects. The main benefit I saw of Postgres or SQLite is that it’s easier to handle relationships in SQL databases, but PayloadCMS handles all that for me, so I just use what’s easier to spin up. If you don’t know which database to use or you’re new, just use MongoDB until you’re able to make a better determination in the future.
Collections is an array of objects used to define what sections of a site you want. For example, you can have a Pages and Blog collection as well as a collection for your Media uploads and marketing material. The blank Payload template includes Users and Media by default, but the options are endless. You can either define the collections in your config or in a separate file to then be imported back into your config. It is recommended that you do the latter so your collections stay separated from your config. We’ll go over how to create collections in a separate file, but for the sake of example, I’ll show you how to get one up in your config file.
Each collection has its own config options, and we’ll get into more detail with those later, but we’ll start with the required fields, which are “slug” and “fields.” The slug is the identifier of the collection and it expects a nonempty string. This is what’s used to label your collection as well, but you can override this using the “labels” option. The slug is usually enough if you’re just adding a “post” collection, but if you wanted to use “blog” as the slug and “post” as the label, you could do that like this.
The “fields” option is used to define what material makes up the collection. We’ll dive into fields later on, but we’ll just add a text field for now. Once these fields are set, you now have a new collection that you can expand upon.
Similarly, you can define Global collections using the global option in your config. These function like collections but without the ability to add multiple globals, like you would be able to add multiple blogs to your Blog collection. This comes in handy if you want to add fields you can edit like trackers or navigation links but without having to create a bunch of individual collection items.
Again, you can (and should) create globals in individual files to then be imported into your config file, but we’ll cover that later on. For now, let’s create a global config in our payload config file.
Let’s add a global config called “nav.” Just like collections, we need a slug to identify what the global is. If we want to, we can use labels to override the slug, which we’ll do so we can show “navigation” instead of “nav” in the admin panel.
Then we need to add fields. We can add an array field by setting the name to “items,” type to “array,” and then “fields” to an array with “name” as “page” and “type” as “text.” When this is done, we can see “navigation” pop up in our admin panel, where we can add navigation links to our project.
Setting a cross-origin resource sharing (or CORS) allows you to accept incoming requests from a whitelist of domains. Typically you will want to at least allow your localhost and your actual domains. This will help you communicate seamlessly between your frontend and backend. It is a good idea to put your primary domain as an environment variable so it can be set when you deploy instead of having to change the code after you deploy. This is helpful when you don’t know what the domain is going to be ahead of time, like when using default Vercel, Railway, or Digital Ocean domain names.
If you think you’re experiencing issues from CORS, you have the ability to include a wildcard string (*) to accept all incoming requests. This is not very secure, though, and you should always try to make this work. Only use the wildcard for troubleshooting.
You can also use an object to set your CORS configuration option. This object accepts origins, which can, again, be an array of whitelisted domains, or a wildcard string. The other option the CORS object will expect is an array of allowed headers. This is a more advanced option that you may not need, but know it’s available should you need the option.
CSRF is a whitelist array of URLs from which your backend can accept cookies. This is just an extra layer of security that is highly recommended to be set. I typically set this to be the same as my CORS setting.
The upload option is where you can set your Payload-wide upload options. The primary reason you need to set this is if you want to limit the filesize of uploaded documents. This needs to be written in bytes, like so.
The last option we’ll go over in this video is the secret. This needs to be a secure string stored in your dotenv file that tells Payload what to use in password salt and hashing. This is a required field, and your project will not run if you don’t have it setup properly. This should have been created when you started a new project, but if not, this is how you’ll do it.
That’s it for extending the Payload CMS config file for now. The fields we have gone over will get you started and on your way to a more fully-featured CMS.
