> From the [Strife developer docs](https://strife.app/docs/reference/globals). Every page is listed in [llms.txt](https://strife.app/docs/llms.txt).

# 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`](https://strife.app/docs/reference/cli/schemas.md):

```ts title="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' }),
      },
    }),
  ],
});
```

| Option   | Description |
| -------- | ----------- |
| `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](https://strife.app/docs/reference/icons.md). |
| `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 config | What 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:

```astro title="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](https://strife.app/docs/reference/webhooks.md) 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`.

- [Schemas](https://strife.app/docs/reference/cli/schemas.md)
