What’s up everyone? In this guide, we’re going to go over more Payload configurations in your Payload config file. Let’s dive in.
In a previous guide, we discussed several config options within the PayloadCMS config file. The options we went over in that guide should have been plenty to get started with in any project you might be working on, so if you haven’t seen that guide yet, please do before continuing.
The other guide includes descriptions of the 2 required config options, so you will want to make sure you understand the db and secret config options before moving forward.
Though we went over several options in that guide, we didn’t go over a few important configuration options. Let’s do that now.
Email
The email field allows you to configure an email adapter for Payload. If this field is not defined, any login-related emails will be logged to the console, which is not very useful. You can set up the email configuration using SMTP, Resend, SendGrid, and more. This allows you to send “forgot password” emails, responses from a form, and much more.
field, which tells Payload how many levels deep in a relationship it should return for a request. The higher the
depth
, the more expensive the database transaction, so use this feature wisely. You typically won’t need to use a depth of more than 1 or 2, so you might want to set that level here instead of typing it in each request on your frontend. Otherwise, you can set this to 0 and define the depth you want to hydrate only on the front end.
It’s important to note that depth has no effect in the GraphQL API, only in REST and the Local API. This is because GraphQL’s depth is based on the shape of your queries.
You will be able to tell if your depth is not sufficient if you only get the item’s ID in your response. You can test different depths and what it returns in the API section of the PayloadCMS admin panel of a specific item.
Max Depth
If you’d like some extra protection against malicious queries that might try to use depth to create large requests to your database, you can set a maxDepth. Normally this defaults to 10, but you can set it to whatever number you’d like. So, if you don’t anticipate ever needing a depth of more than 3, you can set this to 3 and restrict the max depth across your whole application.
You’re also able to set this at the field level if you don’t want to restrict depth at the application level. So, if you set this as 2 on a relationship field, then no matter what you put in your query, the result will only return relationships up to 2 levels deep.
Rate Limit
Note
This option no longer exists in Payload CMS.
To prevent DDoS attacks and other forms of API abuse, you can set a custom rate limit in the PayloadCMS config. This is a number set to control your IP-based rate limiting for all Payload resources.
Localization
Localization allows you to manage multiple languages in one CMS. You can use localization to set the locales you want your CMS to manage. This is not internationalization, which you can enable to translate the Admin Panel as well, more on that later.
You can set your localization object to include an array of strings of locales, which you can set to whatever you want them to be. Each locale array item can accept a locale object, too. For each array item, you can open up a new empty object, provide a unique code for you to identify the language through your API calls for locale and fallbackLocale, and a label, which is a string used for the selector when choosing a language. You can also set your preference for right-to-left text using the rtl option. You also may want to set a fallbackLocale for each locale object.
If you opt in for localization, you’ll need to provide a defaultLocale using the code of your preferred default language. If no locale is specified in your API queries, then this is the locale that will be used by default.
Fallback is true by default. This allows you to allow a field without a localized value to fall back to another locale. If this is set to false, the field without a localization will not return anything.
You can enable localization at the field level but setting localized to true in each field you’d like to have localization included.
i18n
Enabling internationalization will allow the PayloadCMS Admin Panel to be translated. At the time of my writing this guide, there are currently 30 languages supported in internationalization. By default, English is installed with PayloadCMS, but you can add as many languages as you’d like. This language will be selected based on the users preference based on their request to the PayloadCMS dashboard.
You can set a fallbackLanguage to be whatever you’d like the language to be. As I mentioned before, this default language is English, so if that’s your preferred fallback language, then you don’t need to set this option.
You can add supported languages by defining the supportedLanguage option. You’ll need to import each language you’d like to support from the @payloadcms/translations package. You should only import and use the languages you plan on supporting so your project doesn’t bloat from unused JavaScript.
Server URL
Use the server URL config option to set the absolute URL of your app. This cannot include paths; only protocol, domain, and port, which is optional. It is recommended you include this as an environment variable. Not because it’s secure and should be protected, but so you can set your actual domain as an environment variable when the app is deployed.
When you are working with your app locally, you can use http://localhost:3000. When deployed, though, your localhost won’t work, and it needs to be set to your actual domain.
Plugins
There are many plugins that are offered by the PayloadCMS team. These are flexible enough where you can create your own plugin if you need to. We will cover the available plugins in a separate video, but this is where you define the plugins you’d like to use for your PayloadCMS instance.
This option accepts an array of plugins and their individual configurations. You can either define the plugin within the payload config itself or in a separate file, just like with collections and globals.
Sharp
The last configuration option we’ll go over in this video is sharp. If you want to be able to allow your upload collection to crop, set focal points, and automatically resize your media, you will want to install sharp and pass it in your payload config.
Final Thoughts
PayloadCMS is powerful because of its config-based, code-first approach. The configuration file can be built out even further than this, but most of the other options are going to be use-case specific and you may never need to use them.
