XplorerXplorer

Manifest Reference

Manifest Reference

Every Xplorer extension declares its metadata, permissions, and contributions in the xplorer field of package.json.

Full Schema

{
  "name": "my-extension",
  "version": "1.0.0",
  "main": "dist/index.js",
  "type": "module",
  "dependencies": {
    "@xplorer/extension-sdk": "^1.0.0"
  },
  "xplorer": {
    "id": "my-extension",
    "displayName": "My Extension",
    "category": "panel",
    "version": "1.0.0",
    "author": "Your Name",
    "description": "A brief description of what this extension does",
    "icon": "🔧",
    "keywords": ["utility", "files"],
    "homepage": "https://github.com/you/my-extension",
    "repository": "https://github.com/you/my-extension",
    "license": "MIT",
    "permissions": [
      "file:read",
      "ui:notifications"
    ],
    "activationEvents": [
      "onDirectoryOpen",
      "onFileChange"
    ],
    "contributes": {
      "panels": [
        {
          "id": "my-panel",
          "title": "My Panel",
          "location": "right",
          "icon": "🔧",
          "when": "always"
        }
      ],
      "commands": [
        {
          "command": "doSomething",
          "title": "Do Something",
          "category": "My Extension",
          "icon": "▶️"
        }
      ],
      "themes": ["my-dark-theme"],
      "context_menus": [
        {
          "command": "my-extension.doSomething",
          "when": "singleFileSelected",
          "group": "tools"
        }
      ],
      "keybindings": [
        {
          "command": "doSomething",
          "key": "ctrl+shift+d",
          "title": "Do Something"
        }
      ]
    }
  }
}

Fields

Required

| Field | Type | Description | |---|---|---| | id | string | Unique extension identifier. Lowercase, dashes only. Must be globally unique. | | version | string | Semantic version (e.g. 1.0.0, 2.1.0-beta.1). | | author | string | Author name. | | category | string | One of: theme, preview, action, panel, tool, tab, navigation, bottom-tab, editor. |

The name field serves as the display name if displayName is not set.

Optional

| Field | Type | Default | Description | |---|---|---|---| | displayName | string | name | Human-readable name shown in the Extensions panel. | | description | string | — | One-line description. | | icon | string | 🧩 | Emoji shown in the extension bar and panel headers. | | keywords | string[] | [] | Search keywords for the marketplace. | | homepage | string | — | Project homepage URL. | | repository | string | — | Source code URL. | | license | string | — | SPDX license identifier (e.g. MIT, Apache-2.0). | | permissions | string[] | [] | Required permissions. See Permissions. | | activationEvents | string[] | [] | Events that trigger activation. | | contributes | object | — | Declared contributions. See below. |

category

Determines the extension's base class and what it can contribute:

| Category | Base Class | Can Contribute | |---|---|---| | panel | PanelExtension | Sidebar panels, commands | | preview | PreviewExtension | File preview handlers | | action | ActionExtension | Context menu items, commands | | theme | ThemeExtension | Color themes, CSS | | tool | Extension | Commands, decorators, automation | | tab | TabExtension | Custom tab views in the main content area | | navigation | NavigationExtension | Left sidebar navigation entries | | bottom-tab | BottomTabExtension | Bottom panel tabs | | editor | EditorExtension | File editor handlers |

Contributions

The contributes object declares what the extension provides to Xplorer.

contributes.panels

Register sidebar panels.

{
  "panels": [
    {
      "id": "my-panel",
      "title": "My Panel",
      "location": "right",
      "icon": "🔧",
      "when": "always"
    }
  ]
}

| Field | Type | Required | Description | |---|---|---|---| | id | string | Yes | Unique panel identifier. | | title | string | Yes | Display title in the panel header. | | location | string | No | Where to render: right (default), sidebar, bottom. | | icon | string | No | Emoji or icon for the extension bar button. | | when | string | No | Condition for showing the panel (e.g. always, hasFiles). |

contributes.commands

Register named commands.

{
  "commands": [
    {
      "command": "doSomething",
      "title": "Do Something",
      "category": "My Extension",
      "icon": "▶️"
    }
  ]
}

| Field | Type | Required | Description | |---|---|---|---| | command | string | Yes | Command name (auto-prefixed with extension ID at runtime). | | title | string | Yes | Human-readable title for command palette. | | category | string | No | Grouping in the command palette. | | icon | string | No | Icon shown next to the command. |

contributes.context_menus

Add items to the file context menu.

{
  "context_menus": [
    {
      "command": "my-extension.doSomething",
      "when": "singleFileSelected",
      "group": "tools"
    }
  ]
}

| Field | Type | Required | Description | |---|---|---|---| | command | string | Yes | Fully qualified command name to invoke. | | when | string | No | Condition: always, singleFileSelected, multipleFilesSelected. | | group | string | No | Menu group for ordering. |

contributes.keybindings

Register keyboard shortcuts that invoke commands.

{
  "keybindings": [
    {
      "command": "doSomething",
      "key": "ctrl+shift+t",
      "when": "file-explorer",
      "title": "Do Something"
    }
  ]
}

| Field | Type | Required | Description | |---|---|---|---| | command | string | Yes | Command name to invoke (auto-prefixed with extension ID). | | key | string | Yes | Default key combination (e.g. ctrl+shift+t, alt+k). Format: modifier keys joined by +, lowercase. Valid modifiers: ctrl, alt, shift, meta. | | when | string | No | Context where the shortcut is active. Default: file-explorer. | | title | string | No | Human-readable description shown in the shortcuts settings UI. |

Keybindings are automatically registered when the extension activates and unregistered when it deactivates. Users can re-bind extension shortcuts in Settings > Shortcuts.

contributes.themes

Declare theme IDs this extension provides.

{
  "themes": ["my-dark-theme", "my-light-theme"]
}

Activation Events

Control when your extension is activated. If empty, the extension activates immediately.

| Event | Trigger | |---|---| | onDirectoryOpen | User opens or navigates to a directory | | onFileChange | A file in the current directory changes | | onCommand:{command} | A specific command is invoked | | onStartup | App starts (same as no activation events) | | * | Always activate immediately |

Entry Point

The main field in the top-level package.json (not inside xplorer) specifies the compiled entry point:

{
  "main": "dist/index.js"
}

This file must be an ES module that either:

  1. Calls registerExtension() with an extension instance, or
  2. Exports a default Extension instance

Naming Conventions

  • Extension ID: lowercase, dashes only (e.g. file-tagger, tokyo-night-theme)
  • Command names: camelCase (e.g. scanWorkspace, addBookmark)
  • Panel IDs: same as extension ID for single-panel extensions, or {extension-id}-{panel-name} for multi-panel
  • Permission strings: category:action format (e.g. file:read, ui:notifications)

Example: Minimal Panel Extension

{
  "name": "hello-panel",
  "version": "1.0.0",
  "main": "dist/index.js",
  "type": "module",
  "dependencies": {
    "@xplorer/extension-sdk": "^1.0.0"
  },
  "xplorer": {
    "id": "hello-panel",
    "displayName": "Hello Panel",
    "category": "panel",
    "version": "1.0.0",
    "author": "Developer",
    "icon": "👋",
    "contributes": {
      "panels": [{
        "id": "hello-panel",
        "title": "Hello",
        "location": "right",
        "icon": "👋"
      }]
    }
  }
}

Example: Full-Featured Tool Extension

{
  "name": "workspace-linter",
  "version": "2.1.0",
  "main": "dist/index.js",
  "type": "module",
  "dependencies": {
    "@xplorer/extension-sdk": "^1.0.0"
  },
  "xplorer": {
    "id": "workspace-linter",
    "displayName": "Workspace Linter",
    "category": "tool",
    "version": "2.1.0",
    "author": "Dev Team",
    "description": "Automated linting and issue detection for workspaces",
    "icon": "⚡",
    "keywords": ["lint", "workspace", "automation"],
    "license": "MIT",
    "permissions": [
      "file:read",
      "directory:list",
      "ui:notifications",
      "ui:panels"
    ],
    "activationEvents": ["onDirectoryOpen"],
    "contributes": {
      "panels": [{
        "id": "workspace-linter-issues",
        "title": "Lint Issues",
        "location": "right",
        "icon": "⚠️"
      }],
      "commands": [
        {
          "command": "scan",
          "title": "Scan Workspace",
          "category": "Linter"
        },
        {
          "command": "fix",
          "title": "Auto-fix Issues",
          "category": "Linter"
        }
      ],
      "context_menus": [{
        "command": "workspace-linter.scan",
        "when": "singleFileSelected",
        "group": "tools"
      }]
    }
  }
}