Reference

Plugin options

fontsPlugin(options?) is the single entry point; one call registers the three collections, the fontSet global, and the export endpoint. It's zero-config. The collections and global are covered on the Collections page.

Everything the plugin registers is one key under collections (Payload collections) or globals (fontSet is a Payload global, so it lives there, not under collections) — mirroring Payload's own config shape. The plugin's own knobs — charset, families — live in a separate options bucket, kept apart from the collections and globals it registers.

Each collections.<name> / globals.fontSet entry is the same uniform shape: slug renames it (see Renaming below), overrides is a plain Partial<CollectionConfig> (or Partial<GlobalConfig>) merged onto the plugin's config, and options would carry that entry's own plugin knobs — the fonts collections and global have none. globals.fontSet also takes false to skip it.

Pass options to customize. Reference is the interactive view; TypeScript is the same shape in code, every option at its default.

import { fontsPlugin } from '@pro-laico/payload-fonts'

// Every option at its default. This is the zero-config behaviour, written out.
fontsPlugin({
  enabled: true,
  // collections: {                        // optional, no defaults; each is { slug?, overrides? }
  //   font: { overrides: { /* … */ } },         // the visible font typeface collection
  //   fontOriginal: { overrides: { /* … */ } }, // the hidden originals upload collection
  //   fontOptimized: { overrides: { /* … */ } },// the hidden served-WOFF2 upload collection
  // },                                    // overrides is any Partial<CollectionConfig>; `slug` renames it
  // globals: {
  //   fontSet: {}, // {} registers the global as-is; { slug?, overrides? } tweaks it, false skips it
  // },
  options: {
    charset: 'latin',
    // families: [{ key: 'sans' }, { key: 'serif' }, { key: 'mono' }, { key: 'display' }],
    //   ^ the default, written out. Pass your own COMPLETE list to replace it
    //     (spread DEFAULT_FONT_FAMILIES to keep these and add more).
    // access: {
    //   export: () => true, // default: PAYLOAD_SECRET bearer-token check — override only if terminated upstream
    // },
  },
})

Overrides merge non-destructively, by the same rules in every plugin here:

So collections: { fontOriginal: { overrides: { upload: { staticDir } } } } keeps the built-in font-mime whitelist, and adding a field via collections: { font: { overrides: { fields } } } keeps title / family / variable / weights.

Renaming

slug is an ordinary override. Rename anything the plugin registers and every internal reference is rebuilt around the new name — the fontOptimized → font relationship, the fontSet slots, the upload relationships, the cleanup and optimize hooks' queries, and the slugs the export endpoint and payload fonts:download read:

fontsPlugin({
  collections: { font: { slug: 'typefaces' } },
  globals: { fontSet: { slug: 'typography' } },
})
// → editors get a `typefaces` collection and a `typography` global; nothing else to update.

Renaming is a schema change, not a label change: on an existing database it's a migration, so do it before you have font data (or migrate the tables/collections yourself).

Environment variables

Both commands write files, so both read the output vars. Only the transport differs: payload fonts:download gets its database connection from your Payload config, so the FONT_DOWNLOAD_URL / endpoint pair is dead weight there.

CLI commands

Endpoints

GET /fonts/export is gated by options.access.export, which defaults to the PAYLOAD_SECRET bearer-token check the download CLI sends — a machine endpoint with no user session. Override it only if you terminate auth upstream. See Gating endpoints.

Exports

Collections & globals

fontsPlugin registers the font / fontOriginal / fontOptimized collections and the fontSet global. Their fields are documented on Collections.