Skip to content
Strife Docs

Reference

Global configs

Declare site-wide settings such as the navigation or the footer as global configs in strife.config.ts. Editors fill them in from the team menu and your site reads the published values by id.

A global config is one document of site-wide settings: the navigation, the footer, the cookie banner, the site's contact details. Each global has a fixed set of fields that you declare in strife.config.ts. Editors fill it in from the team menu, as a draft they publish. Your site reads the published values by an id you already know.

Before globals, the usual approach was a template plus one content document, and the site kept that document's id in its configuration. A global replaces both:

  • There is no id to copy between environments. The id comes from the global's name.
  • Globals are not listed in the content list.
  • An editor cannot create a second instance or delete the global.

Declare a global

Add a globals list to defineConfig. Each entry is a defineGlobal, and its fields take the same fields.* builders as defineType:

strife.config.ts
import { defineConfig, defineGlobal, fields, glob } from '@strifeapp/strife/schema';

export default defineConfig({
  schema: glob('./src/schemas/**/*.ts'),
  globals: [
    defineGlobal({
      name: 'footer',
      label: 'Footer',
      icon: 'layout',
      fields: {
        heading: fields.text({ label: 'Heading', localizable: true }),
        description: fields.paragraph({ label: 'Description', localizable: true }),
        newsletter: fields.toggle({ label: 'Show newsletter sign-up' }),
      },
    }),
    defineGlobal({
      name: 'site-settings',
      label: 'Site settings',
      icon: 'settings',
      fields: {
        contactEmail: fields.text({ label: 'Contact email' }),
      },
    }),
  ],
});
OptionDescription
name
Required. The global's identity and part of its id. Lowercase letters, digits and hyphens, starting with a letter, at most 64 characters (footer, site-settings). draft, scheduled and snapshot are not allowed.
label
Shown in the team menu. Defaults to name.
icon
Required. The icon shown next to the global in the team menu. See Icons.
fields
Required. An object of fields.* builders, exactly as in defineType. localizable: true gives a field one value per locale.

A team can have at most 50 globals. The team menu lists them in the order of the globals list.

Warning:

The name is the identity. If you rename a global, you get a new, empty global, and the old one is hidden with its values. Pick names you can keep.

Push it

strife push sends the globals to the linked team together with the templates, and lists what changed:

✓ Pushed globals (2 globals)
  Added globals: footer, site-settings

strife push checks the list before it sends anything. An invalid name, a reserved name, a duplicate name or more than 50 globals stops the push with a message that names the global, and nothing on the team changes.

Your configWhat happens on the team
A global is in globals
It is added, or its label, icon, order and fields are updated.
A global is no longer in globals
It is hidden from editors. Its values are kept. Push it again and it comes back with them.
globals: []
Every global is hidden. Their values are kept.
No globals key
Globals are left as they are. A push from an older branch or another project does not hide them.

Changing a global's fields works like changing a template's fields. The values of fields that still exist are kept, and the values of removed fields are hidden, not deleted.

strife push --dry-run prints the globals it would send without changing anything.

How editors use it

Editors open globals from the team's … menu, where every global the team has is listed under Configurations. A global opens in a full-screen editor with its fields, a status card, and Discard and Publish at the bottom.

  • An edit is saved as a draft. Your site does not see it until an editor publishes.
  • On a team with several locales, the locale switcher and per-locale publish and discard work as they do for pages.
  • Editing and discarding need the same permission as editing content. Publishing needs the same permission as publishing content.
  • A global that has never been published opens with empty fields.

Read it on your site

The published values live in a document with the id Configurations/globals/<name>. Load it by id with the store you already use:

src/layouts/Layout.astro
---
import { store } from 'strife:store';

type Footer = {
  heading?: Record<string, string>;
  description?: Record<string, string>;
  newsletter?: boolean;
};

const locale = Astro.currentLocale ?? 'en';
const session = store.openSession();
const footer = await session.load<Footer>('Configurations/globals/footer');

const heading = footer?.heading?.[locale] ?? footer?.heading?.en;
---

{heading && <footer><h2>{heading}</h2></footer>}

Keep these in mind:

  • The document exists only after the first publish. Until then, load returns null. Write your code so that the site still renders without it.
  • Each declared field has the shape its definition says. A localizable field holds one value per locale, such as { "en": "Contact us", "sv": "Kontakta oss" }. Any other field holds a plain value. If you change a field's localizable setting, the next publish converts the stored value: a plain value becomes the default locale's, and a per-locale value becomes the default locale's value. If a locale has no value yet, fall back to another locale yourself.
  • Read only the fields you declared. The document also carries Strife's own properties, such as status, locales and who published it last. Those are not part of the contract and can change. A field you remove from the config keeps its last value in the document.
  • Only published values are stored at this id. A draft is never stored there, so live preview does not show unpublished changes to a global.
  • References and links are stored as they are in pages. Strife does not resolve them to URLs for you.
  • Globals are not in the Content/ByUrl index. Always load a global by id.

Caches

Publishing a global sends a content.published webhook event with kind global. Its documentId is the global's id, urls is empty and scope is site. A global usually shows on every page, so a receiver that follows scope refreshes the whole site.

strife push sends no event, even when it adds, changes or hides a global. A push changes what editors see, never what your site reads.

Requirements

Global configs need @strifeapp/strife 1.25.0 or later, which brings @strifeapp/schema 0.20.0, and @strifeapp/cli 0.1.0-alpha.20 or later. With an older SDK, defineGlobal does not exist. An older CLI does not send globals.

SchemasDefine content types in code with defineType and fields, and register them with strife.config.ts — an alternative to building templates by hand in Strife Studio.