Skip to main content

Extension Manifest Reference

:::info Auto-generated This document is auto-generated from ExtensionManifestSchema.json. Do not edit manually. Regenerate with: npm run generate:manifest-docs :::

Schema for extension.json. The manifest loader rejects anything that fails this schema. See packages/core/src/Extensions/ExtensionManifest.ts for the matching TypeScript shape and docs/desktop-refactor/spec-A.extension-api.md §Manifest for the design rationale.

Required fields: id, name, version, publisher, engines

Top-Level Properties​

PropertyTypeRequiredDescription
idstringYesext.. — kebab-case labels separated by dots. Pattern: ^ext\.[a-z0-9]+(?:-[a-z0-9]+)*\.[a-z0-9]+(?:-[a-z0-9]+)*$
namestring or { key, params }Yes
displayNamestring or { key, params }No
versionstringYesSemver version of the extension package. Pattern: ^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$
publisherstringYesPattern: ^[a-z0-9]+(?:-[a-z0-9]+)*$
descriptionstring or { key, params }No
categoriesstring[]NoUnique items
keywordsstring[]NoUnique items
homepagestringNoFormat: uri
repositorystringNoFormat: uri
bugsstringNoFormat: uri
licensestringNo
pricing"free", "freemium", "paid"NoValues: free, freemium, paid
iconstringNo
previewbooleanNo
mainstringNo
permissionsPermission[]NoUnique items
activationEventsstring[]NoUnique items
l10nstringNo

engines​

Required.

PropertyTypeRequiredDescription
bibleAppstringYesSemver range against EXTENSION_API_VERSION.

network​

Optional.

PropertyTypeRequiredDescription
allowedHostsAllowedHost[]YesMin items: 1

network.allowedHosts items​

PropertyTypeRequiredDescription
hoststringYesHostname or *.subdomain wildcard. Wildcards match one or more labels. Min length: 1
purposestring or { key, params }Yes
methods"GET", "POST", "PUT", "PATCH", "DELETE", "HEAD"[]NoUnique items

privacy​

Privacy declaration — what data the extension collects and sends to its backend.

Optional.

PropertyTypeRequiredDescription
dataCollection"analytics", "crash-reports", "user-content", "personalization", "none"[]YesMin items: 1. Unique items
privacyPolicyUrlstringNoFormat: uri

webviews​

Optional.

PropertyTypeRequiredDescription
cspobjectNo

webviews.csp​

PropertyTypeRequiredDescription
img-srcCspSourceListNo
font-srcCspSourceListNo
style-srcCspSourceListNo
connect-srcCspSourceListNo
media-srcCspSourceListNo
frame-srcCspSourceListNo

runtime​

Optional.

PropertyTypeRequiredDescription
maxMemoryMBintegerNoMaximum V8 heap size in MB for the worker process. Clamped to 256–1024 MB. Default 256. Min: 256. Max: 1024

contributes​

Optional. Declares static contributions the extension makes to the host application.

Contribution PointTypeDescription
commandsContributedCommand[]See details below
panelTypesPanelTypeDef[]See details below
menusobjectSee details below
configurationobjectSee details below
providersobjectSee details below
displayModesDisplayModeDescriptor[]See details below
themesContributedTheme[]See details below
fontsContributedFont[]See details below
iconsContributedIcon[]See details below
stylesContributedStyle[]See details below
fileImportersContributedFileImporter[]See details below
apiExportsContributedApiExport[]See details below
bibleProvidersBibleProviderDescriptor[]See details below
commentaryProvidersCommentaryProviderDescriptor[]See details below
dictionaryProvidersDictionaryProviderDescriptor[]See details below
bookProvidersBookProviderDescriptor[]See details below

contributes.commands​

PropertyTypeRequiredDescription
idstringYesMin length: 1
titlestring or { key, params }Yes
categorystring or { key, params }No
shortcutKeybindingDescriptor | arrayNo
whenstringNo
handlerEndpointstringNo
orderintegerNo
hiddenbooleanNo

contributes.panelTypes​

PropertyTypeRequiredDescription
idstringYesMin length: 1
titlestring or { key, params }Yes
iconstringNo
uiEntrystringYes
defaultBucket"left", "right", "bottom", "unknown"NoValues: left, right, bottom, unknown
writingPanebooleanNo

contributes.menus​

A map of menu location IDs to arrays of menu items.

Menu item properties:

PropertyTypeRequiredDescription
idstringNo
labelstring or { key, params }Yes
iconstringNo
commandstringYes
argsanyNo
whenstringNo
orderintegerNo
separatorBeforebooleanNo
separatorAfterbooleanNo

contributes.configuration​

Accepts either a JSON Schema { "$ref": "..." } pointing to an external schema file, or an inline JSON Schema object defining the extension's configuration shape.

contributes.providers​

A map of provider type IDs to handler endpoint strings.

contributes.displayModes​

PropertyTypeRequiredDescription
idstringYesMin length: 1
labelstring or { key, params }Yes
kind"overlay", "replace"YesValues: overlay, replace
renderEndpointstringYes
applicableLanguagesstring[]No

contributes.themes​

PropertyTypeRequiredDescription
idstringYes
labelstring or { key, params }Yes
pathstringYes

contributes.fonts​

PropertyTypeRequiredDescription
idstringYes
familystringYes
filesstring[]YesMin items: 1
fallbackstringNo

contributes.icons​

PropertyTypeRequiredDescription
idstringYes
pathstringYes

contributes.styles​

PropertyTypeRequiredDescription
pathstringYes
scope"verse", "panel", "global"YesValues: verse, panel, global

contributes.fileImporters​

PropertyTypeRequiredDescription
idstringYes
labelstring or { key, params }Yes
extensionsstring[]YesMin items: 1
handlerEndpointstringYes

contributes.apiExports​

PropertyTypeRequiredDescription
methodstringYesPattern: ^[A-Za-z_$][A-Za-z0-9_$]*$
descriptionstring or { key, params }No
handlerEndpointstringYes

contributes.bibleProviders​

PropertyTypeRequiredDescription
idstringYes
namestring or { key, params }Yes
abbreviationstringYes
languagestringNo
capabilities"lookup", "range", "iterate", "remote"[]Yes
fetchEndpointstringYes
rangeEndpointstringNo
iterateEndpointstringNo

contributes.commentaryProviders​

PropertyTypeRequiredDescription
idstringYes
namestring or { key, params }Yes
abbreviationstringYes
languagestringNo
capabilities"lookup", "range", "iterate", "similarity", "remote"[]Yes
fetchEndpointstringYes
rangeEndpointstringNo
iterateEndpointstringNo
similarityEndpointstringNo

contributes.dictionaryProviders​

PropertyTypeRequiredDescription
idstringYes
namestring or { key, params }Yes
abbreviationstringYes
languagestringNo
capabilities"lookup", "search", "iterate", "strongs", "lemma", "morphology", "remote"[]Yes
fetchEndpointstringYes
searchEndpointstringNo
iterateEndpointstringNo
morphologyEndpointstringNo

contributes.bookProviders​

PropertyTypeRequiredDescription
idstringYes
namestring or { key, params }Yes
abbreviationstringYes
languagestringNo
capabilities"lookup", "iterate", "remote"[]Yes
fetchEndpointstringYes
listEndpointstringNo
iterateEndpointstringNo

Type Definitions​

These types are referenced throughout the manifest schema.

LocalizedString​

One of:

  • A plain string
  • An object with properties: key, params

Permission​

One of: "bible:read", "commentary:read", "dictionary:read", "book:read", "notes:read", "notes:write", "highlights:read", "highlights:write", "bookmarks:read", "bookmarks:write", "bible:provide", "commentary:provide", "dictionary:provide", "book:provide", "search:provide", "display-mode:provide", "import:provide", "ai:provide", "tts:provide", "storage", "storage:secrets", "storage:database", "ui:contribute-pane", "ui:verse-decorator", "ui:verse-hover", "ui:context-menu", "ui:notification", "ui:status-bar", "ui:media", "commands:register", "tasks", "network", "network:oauth", "extensions:call", "fs:read-user", "fs:write-user", "fs:managed-folder"

AllowedHost​

PropertyTypeRequiredDescription
hoststringYesHostname or *.subdomain wildcard. Wildcards match one or more labels. Min length: 1
purposestring or { key, params }Yes
methods"GET", "POST", "PUT", "PATCH", "DELETE", "HEAD"[]NoUnique items

KeybindingDescriptor​

PropertyTypeRequiredDescription
keystringYes
macstringNo
whenstringNo

Shortcut​

One of:

Permissions Reference​

The permissions array accepts the following values:

bible

  • "bible:read"
  • "bible:provide"

commentary

  • "commentary:read"
  • "commentary:provide"

dictionary

  • "dictionary:read"
  • "dictionary:provide"

book

  • "book:read"
  • "book:provide"

notes

  • "notes:read"
  • "notes:write"

highlights

  • "highlights:read"
  • "highlights:write"

bookmarks

  • "bookmarks:read"
  • "bookmarks:write"

search

  • "search:provide"

display-mode

  • "display-mode:provide"

import

  • "import:provide"

ai

  • "ai:provide"

tts

  • "tts:provide"

storage

  • "storage"
  • "storage:secrets"
  • "storage:database"

ui

  • "ui:contribute-pane"
  • "ui:verse-decorator"
  • "ui:verse-hover"
  • "ui:context-menu"
  • "ui:notification"
  • "ui:status-bar"
  • "ui:media"

commands

  • "commands:register"

tasks

  • "tasks"

network

  • "network"
  • "network:oauth"

extensions

  • "extensions:call"

fs

  • "fs:read-user"
  • "fs:write-user"
  • "fs:managed-folder"