Plugin Overview

Foxel distributes plugins as .foxpkg files: ZIP archives with manifest.json at the root. A plugin can provide file viewers, standalone apps, FastAPI routes, file processors, or backend features alone.

This guide follows the current Foxel source: host API 1.0.0, package format 1.0. The contracts live in web/src/plugins/sdk/v1.ts, web/src/plugins/externals.ts, and domain/plugins/. Your plugin's own version is separate from both versions.

Choose a starting point

Goal	Guide
Build and install your first plugin	Complete example: JSON Viewer
Check naming, manifest fields, and workflow	Development guide
Build a UI, read files, and call the host	Frontend development
Add APIs or file processors	Backend development
Verify, install, and publish a package	Build and package

Extension points

Extension	Manifest declaration	Entry point
File viewer / editor	`frontend.entry`, `supportedExts`	`FoxelRegister({ mount })`, with file context
Standalone app	`frontend.entry`, `openApp: true`	`mountApp(container, { host })`
HTTP API	`backend.routes`	Python file exporting `router: APIRouter`
File processor	`backend.processors`	Python file exporting `PROCESSOR_FACTORY`

openApp: true requires mountApp; the host does not substitute mount for it. A backend-only plugin does not need frontend/index.js.

Package layout and loading

text

com.example.jsonviewer.foxpkg
├── manifest.json
├── frontend/
│   ├── index.js          # IIFE entry
│   ├── player.css        # Declared in frontend.styles
│   └── icon.svg
└── backend/              # Optional
    ├── routes/api.py
    └── processors/format_json.py

Installation validates the manifest, archive files, host API range, and Python dependencies before loading the backend and activating the version. Placing source in the repository's plugins/ directory does not install it automatically.

When opening a frontend, the host creates a plugin-frame.html iframe, injects shared dependencies, loads optional capabilities, adds styles, loads the entry script, waits for window.FoxelRegister(...), and calls mount or mountApp. Closing the window runs plugin cleanup.

Seven official plugin repositories

Foxel-Studio is the official plugin organization. Use these seven repositories as references. The local Foxel repository also includes corresponding projects under plugins/; the target host implementation defines compatibility.

Directory	Useful patterns
cc.foxel.imageviewer	Image viewing, metadata, directory navigation
cc.foxel.markdown	React and the host `react-markdown` capability
cc.foxel.monaco	Monaco editor and text file access
cc.foxel.video	Artplayer capability and media URLs
cc.foxel.music	React player and lifecycle management
cc.foxel.pdf	Native DOM entry and PDF previews
cc.foxel.office	Word, Excel, and PowerPoint previews

Check each project's package.json, vite.config.ts, contract.ts, and pack.py before copying it. Script names and resource lists belong to individual plugin projects; the host does not supply them. The old plugins/text-editor template path is no longer applicable.