Manifest Reference

Manifest Reference

Each extension must include a package.json manifest in the repository root.

Required Fields

Field	Description
id	Unique extension ID in publisher.extension-name format
name	Display name
version	Semantic version
repository	Public GitHub repository URL
license	SPDX license identifier
extensionType	api, iframe, or webview
main	Runtime entry module. Required for iframe/webview extensions and api extensions that run code; theme-only and icon-theme-only api extensions can omit it
permissions	Permissions required by the extension
engines	Supported Sigma File Manager version range

API extensions that run code must also set "type": "module" so the host can load them as ESM. This is a standard npm field, not validated by the manifest schema, but omitting it will cause runtime failures.

Common Optional Fields

Field	Description
$schema	Local manifest schema path for editor validation and completions
previousName	Previous extension name for rename support
publisher	Publisher metadata
icon	Extension icon path
banner	Extension banner path
media	Preview images or videos for the extension details overview
categories	Marketplace categories
tags	Search keywords
platforms	Supported operating systems
activationEvents	Activation triggers
contributes	Static contributions such as commands, UI, settings, and keybindings
binaries	Host-managed external binaries declared in the manifest
files	Standard npm publish allowlist. Has no effect on tag-based Git archive installs; use .gitignore to exclude files from the tagged tree instead
scripts	Optional local build and packaging scripts

activationEvents entries may be built-in strings such as onStartup, onInstall, onUninstall, onEnable, onDisable, onUpdate, or onLocaleChange, or a command hook onCommand:<fullCommandId> such as onCommand:sigma.video-downloader.download-video (see API Reference lifecycle).

Identity and Publisher

Use an identity that clearly belongs to the extension author:

• id should use a stable publisher.extension-name format, usually based on your GitHub user or organization name.
• publisher.name and publisher.url should identify the person or organization that maintains the extension.
• Do not use sigma, sigma-file-manager, sfm, sigma-hub, official badges, official-looking wording, or Sigma File Manager branding in a way that suggests the extension is maintained by the Sigma File Manager team unless you have explicit approval.
• If you start from a template, replace every placeholder such as your-name, my-extension, and My Extension before publishing.
• Marketplace submissions should keep the manifest identity and the marketplace registry.json identity aligned: same id, same repository, and publisher details that point to the same author.

media

Optional array of gallery items for the extension overview. Each object requires title, src, and type. Use type: image or video. src is a path relative to the extension root or an absolute http/https URL. Commit files you ship by path (for example screenshots next to package.json) so they are present in tag-based installs.

"media": [
  { "title": "Preview", "src": "preview-1.jpg", "type": "image" }
]

These files ship with the extension, so their size affects every install and update. Prefer compact assets: compress images (modern formats such as WebP, or tuned JPEG/PNG), use resolution that matches how previews are displayed, and avoid oversized screenshots. For video, keep clips short, encode for efficient delivery, and trim anything that does not help users understand the extension. The goal is the smallest files that still read clearly in the gallery.

Permissions

Permission	Grants Access To
contextMenu	sigma.contextMenu
commands	sigma.commands
sidebar	Sidebar contributions
toolbar	Toolbar contributions
notifications	sigma.ui.showNotification()
dialogs	sigma.ui.showDialog() and sigma.dialog
fs.read	Read-only filesystem operations
fs.write	Write and download filesystem operations
shell	sigma.shell and read-only sigma.binary access
clipboard	sigma.ui.copyText() and sigma.ui.clipboardWrite()
openUrl	sigma.context.openUrl()

Extension Types

Type	Description	Entry point (main)
api	ESM module with full sigma API access, or manifest-only static contributions	Usually dist/index.js for extensions that run code; optional for theme-only and icon-theme-only extensions
iframe	Sandboxed iframe integration	index.html
webview	Separate Tauri window integration	index.html

For api extensions that run code, main must be the file the host actually loads. TypeScript projects compile src/ to dist/ and commit build output so tag-based installs work without running npm run build on the client (Submitting to the Marketplace). Extra assets (for example dist/embed.js) are referenced by URL from code or contributes as needed. API extensions that only contribute themes or icon themes through package.json can omit main.

contributes

Use contributes for declarative features that the app can register from the manifest.

contributes.themes

Declares color themes that appear alongside the app's built-in themes. Theme contributions extend the host app's built-in light/dark token sets, so you usually only need to override the variables you want to change.

If an API extension only contributes themes and does not run any code, it can omit main and does not need an empty index.js.

Field	Description
id	Unique theme identifier within the extension, using lowercase letters, numbers, and hyphens
title	Display title
description	Optional help text
baseTheme	Built-in token set to extend: light or dark
variables	CSS custom properties keyed by variable name

Color variable values should use HSL channel values without the hsl() function, for example "230 20% 10%", not "hsl(230 20% 10%)".

"themes": [
  {
    "id": "midnight",
    "title": "Midnight",
    "baseTheme": "dark",
    "variables": {
      "--background": "230 20% 10%",
      "--primary": "200 80% 60%"
    }
  }
]

contributes.iconThemes

Declares navigator icon themes that appear in Settings > Appearance > Icon Theme. Users can choose separate icon themes for folders and files, so one contributed icon theme can be used for either or both entry types.

If an API extension only contributes icon themes and does not run any code, it can omit main and does not need an empty index.js.

Field	Description
id	Unique icon theme identifier within the extension
label	Display label shown in Settings
path	Relative path to the icon theme JSON file

"iconThemes": [
  {
    "id": "catppuccin-frappe",
    "label": "Catppuccin Frappe",
    "path": "dist/frappe/theme.json"
  }
]

Icon theme JSON files can define iconDefinitions, default file and folder icons, and association maps such as fileExtensions, fileNames, and folderNames. Icon paths inside iconDefinitions are resolved relative to the theme JSON file and must stay inside the extension directory. Ship every referenced icon asset in the tagged release.

{
  "file": "_file",
  "folder": "_folder",
  "iconDefinitions": {
    "_file": {
      "iconPath": "./icons/file.svg"
    },
    "_folder": {
      "iconPath": "./icons/folder.svg"
    }
  },
  "fileExtensions": {
    "ts": "_file"
  },
  "folderNames": {
    "src": "_folder"
  }
}

contributes.commands

Declares commands that appear in extension metadata and can be surfaced by the app.

Field	Description
id	Unique command identifier within the extension, usually a short ID such as download-video
title	Display title
description	Optional help text
icon	Optional icon name
shortcut	Optional default shortcut

Use short command IDs in contributes.commands and in sigma.commands.registerCommand(). Use the full command ID only in places such as activationEvents, for example onCommand:sigma.video-downloader.download-video.

contributes.contextMenu

Declares context menu items.

Field	Description
id	Unique item identifier, usually a short ID such as convert
title	Display title
icon	Optional icon name
group	Menu group
order	Sort order within the group
when.selectionType	single, multiple, or any
when.entryType	file, directory, or any
when.fileExtensions	Restricts file extensions

Use short IDs in contributes.contextMenu and in sigma.contextMenu.registerItem().

contributes.sidebar

Declares sidebar pages.

Field	Description
id	Unique page identifier
title	Sidebar label
icon	Lucide icon name
order	Optional sort order
url	Optional page path relative to the extension root, such as embed.js, dist/embed.js, or index.html
shortcutCommandId	Optional command ID to activate the sidebar page via a keyboard shortcut

contributes.toolbar

Declares toolbar dropdowns.

Field	Description
id	Unique dropdown identifier
title	Dropdown title
icon	Optional icon name
items	Dropdown item list

Toolbar item fields:

Field	Description
id	Unique item identifier
title	Display title
icon	Optional icon
commandId	Command executed on click
separator	Renders the item as a separator

contributes.configuration

Declares extension settings shown in the Settings UI.

Field	Description
title	Section title
properties	Setting definitions keyed by name

Supported property fields include:

Field	Description
type	string, number, boolean, or array
default	Default value
description	User-facing description
enum	Allowed values
enumDescriptions	Labels for enum values
minimum / maximum	Numeric constraints
minLength / maxLength	String constraints
items	Item type for arrays

contributes.keybindings

Declares default keyboard shortcuts for extension commands.

Field	Description
command	Command ID without the extension prefix
key	Shortcut string such as ctrl+shift+h
when	Activation condition

Supported when values:

Value	Meaning
always	Active globally
fileSelected	Active when a file is selected
directorySelected	Active when a directory is selected
singleSelected	Active for a single selected entry
multipleSelected	Active for multiple selected entries
navigatorFocused	Active when the file browser has focus

If a keybinding conflicts with an app shortcut or another extension shortcut, it is skipped.

binaries

Use binaries when your extension depends on external tools such as ffmpeg, yt-dlp, or deno. The app installs, verifies, caches, reuses, and removes these binaries from the manifest declaration.

Each binary definition supports:

Field	Description
id	Shared binary identifier used at runtime with sigma.binary.getPath() or sigma.binary.getInfo()
name	Human-readable label shown in the UI
version	Pinned version used for install and sharing
executable	Optional default executable path within the downloaded asset
repository	Optional upstream project URL
platforms	Optional list of supported operating systems
assets	Platform-specific downloadable assets

Each asset supports:

Field	Description
platform	windows, macos, or linux
arch	Optional list of supported architectures: x64 or arm64
downloadUrl	Exact asset URL downloaded by the host
integrity	Required SHA-256 hash in the form sha256:<hex>
archive	Whether the asset must be extracted before use
executable	Executable file path inside the asset when it differs by platform

Declare exact, versioned assets. Do not rely on mutable latest URLs for published extensions.

For FFmpeg, the upstream project only distributes source code; ffmpeg.org/download.html links to community builds. BtbN FFmpeg-Builds publishes a moving latest release whose *-latest-* filenames are rebuilt often; for a stable URL and hash, pin a dated autobuild tag (for example autobuild-2026-04-06-13-14) and the matching ffmpeg-n8.1-*-win64-gpl-8.1.zip / …-linux64-…tar.xz asset names from that release’s checksums.sha256. GyanD Windows builds use version-tagged GitHub releases. evermeet.cx provides macOS Intel static ffmpeg archives (Apple Silicon often runs the Intel binary via Rosetta). Recompute integrity whenever you change the pinned file.

Example Manifest

{
  "$schema": "./node_modules/@sigma-file-manager/api/manifest.schema.json",
  "id": "publisher.extension-name",
  "name": "Extension Name",
  "version": "1.0.0",
  "type": "module",
  "repository": "https://github.com/publisher/extension-name",
  "license": "MIT",
  "extensionType": "api",
  "main": "dist/index.js",
  "permissions": ["commands", "shell"],
  "binaries": [
    {
      "id": "ffmpeg",
      "name": "FFmpeg",
      "version": "8.1",
      "repository": "https://ffmpeg.org",
      "assets": [
        {
          "platform": "windows",
          "arch": ["x64"],
          "downloadUrl": "https://github.com/BtbN/FFmpeg-Builds/releases/download/autobuild-2026-04-06-13-14/ffmpeg-n8.1-7-ga3475e2554-win64-gpl-8.1.zip",
          "integrity": "sha256:<sha256-hex>",
          "archive": true,
          "executable": "bin/ffmpeg.exe"
        }
      ]
    }
  ],
  "engines": {
    "sigmaFileManager": ">=2.0.0"
  }
}

Packaging Notes

Ship every runtime asset the extension needs: built output when main references it, CSS, fonts, icons, and locale files. Do not publish node_modules. Tag-based installs use a Git archive; see Submitting to the Marketplace.

Continue

← Previous: Getting Started

Next: API Reference →