Per-request values
Make a few config values functions of the Worker env and the site's content, so one build can serve many deployments.
On this page
This page covers config values that can be a function instead of a constant: which ones, what the function receives and when it runs.
Most config is the same for every deployment of your app. A few values are not. If you run one Worker per site from the same build (a platform for many customers, say), the email sender, the admin title and a contact address differ per site. They live in each Worker's variables or in the site's own content, and you cannot know them when you build.
Those options accept a resolvable value: a constant, or a function of the request's context.
import { defineConfig } from '@kitcms/core';
export default defineConfig({
admin: {
title: async ({ cms }) => String((await cms.findGlobal('site'))?.siteName ?? 'My site'),
},
email: {
from: ({ env }) => ({ address: String(env.EMAIL_FROM), name: 'Website' }),
},
collections: [],
});What the function receives
(ctx: { env, cms }) => T | Promise<T>| Property | What it is |
|---|---|
env |
The Worker's variables and secrets. |
cms |
The Local API acting as the system, for reading the site's content whoever is asking. |
cms is read-only. Reads ignore access rules, so a value can come from content that a visitor could not read themselves. Any write (create, update, delete and so on) throws. A value computed from content can never change it.
cms is not typed to your config here, so documents come back with unknown field values. Convert them (String(...), a typeof check) before you return them.
The function runs on every use, not once at startup. If it is expensive, cache inside it.
Which values accept one
| Option | Used for |
|---|---|
email.from, email.replyTo |
The sender of each message. See Email. |
admin.title |
The admin header, the browser title and emails. See Admin branding. |
enquiries notify (per form) |
Who is emailed about a submission. See Enquiries. |
enquiries turnstile.siteKey |
The Turnstile site key. |
entitlements manageUrl |
The "Manage plan" link. See Entitlements. |
Plugin authors can use the same thing: Resolvable<T> and resolveValue() come from @kitcms/core, and endpoints and panels receive the context as runtime. See Writing a plugin.
When values are checked
- A constant is checked when the config loads, so a bad value is a startup error.
- A function is checked when it is used, because it has no value before that. What happens to a bad result depends on the option:
| Option | A bad or failed result |
|---|---|
email.from |
The message is not sent: EmailNotConfiguredError. The name is cleaned. |
email.replyTo |
Dropped. A typo in a site setting must not stop email. |
admin.title |
The admin shows kitcms. A thrown error is logged. |
enquiries notify |
Addresses that are not valid are skipped. With none left, the submission is stored without a notification. |
enquiries turnstile.siteKey |
An empty value means the form definition has no site key, so no widget is shown. Submissions still need a valid token, so the form cannot be submitted. |
entitlements manageUrl |
Core drops anything that is not an https: or /-relative link. |
Why not read env yourself?
You can, in your own code. These options are read by kitcms itself, for the admin, for emails and for plugin endpoints, so a function is the only place to say where the value comes from.