What can you build? (Plugin types)
Plugins extend Phials by registering one or more providers. A provider represents a specific capability, such as a custom command, a file preview component, or a visual theme. When a plugin activates, Phials registers its providers and hooks them into the user interface.
A single plugin can register multiple providers. For example, a Markdown plugin might register a preview provider to render documents, a metadata provider to extract frontmatter headers, and a command provider to add file creation buttons to the toolbar.
Full TypeScript definitions are available in the phials-plugin-example repository under sdk/ and in the Type references documentation directory. This page provides a conceptual map of the available provider types.
See also: Plugin system overview, Getting started, and Plugin API and lifecycle.
The Toolkit
| Provider type | Description |
|---|---|
| Command | Registers user actions for toolbars, context menus, and keyboard shortcuts. |
| Preview | Adds custom file viewers, editors, and grid thumbnail renderers. |
| Metadata | Extracts structured information from files to display in columns and details. |
| View | Implements custom directory layouts in the main browser area. |
| Module | Adds dockable utility panels to the sidebars or bottom panel. |
| Theme | Adds custom light and dark color schemes. |
command
Commands define user actions that can be triggered from multiple places in the UI. Instead of writing separate code for a toolbar button, a context menu item, and a keyboard shortcut, you define a single command with its action and default placements. Phials surfaces the action in the requested areas, such as the path bar, context menus, selection bar, header, or command palette. This centralized design also lets users customize keyboard shortcuts and toolbar locations.
Commands support context-aware execution. By using when clauses or context keys, you can configure a command to enable or show itself only when specific conditions are met, such as when a file of a certain MIME type is selected.
Example: The phials-plugin-example repository registers a demonstration command in src/main.ts.
Guide: Command providers
preview
Preview providers configure how Phials displays specific file types. While many previews function as read-only viewers, they can also implement full editing interfaces.
You provide Svelte components that match files based on their extension, MIME type, or custom matching functions. Previews can target different display sizes:
- A
thumbnailfor the explorer grid view. - A
previewcomponent for the side-docked preview pane. - A
fullscreenview that occupies the main editor tab.
Example: A 3D model viewer plugin can render a static thumbnail in the grid and mount an interactive WebGL viewport in the main pane.
Guide: Preview providers
metadata
Metadata providers read file contents and extract structured information, such as camera details or media durations. This extracted data is displayed in the Details pane and can be configured as sortable columns in the list view. Multiple metadata providers can target the same file format; Phials runs them concurrently and merges their fields.
Example: An image plugin can parse EXIF headers to retrieve exposure settings and focal lengths, exposing them as sortable columns in Phials.
Guide: Metadata providers
view
View providers let you replace the standard grid and list explorer layouts with custom directory views. You supply a Svelte component that receives the current list of directory entries, and Phials adds your custom view option to the layout toolbar.
Example: A calendar view that arranges files along a timeline based on their creation dates, or a Kanban board view that groups task files by status tags.
Guide: View providers
module
Module providers add custom, dockable interfaces to the Phials workspace sidebars or bottom panel. Unlike fullscreen previews which link directly to a specific file, modules are independent tools that remain active while the user navigates different directories.
Example: A persistent note-taking panel, a Git status monitor, or a custom search utility.
Guide: Module providers
theme
Theme providers register custom color palettes. You define light and dark theme configurations using CSS variables that map to Phials design tokens, making them selectable in the settings panel.
Guide: Theme providers