What can you build? (Plugin Types)
In Phials, plugins extend the app by registering providers. A provider is a specific piece of functionality—like a new command, a custom file preview, or a new theme. When your plugin activates, it hands these providers to Phials, which wires them up to the right parts of the UI.
A single plugin can register as many providers as it wants. For example, a “Markdown” plugin might register a preview provider to render markdown files, a metadata provider to extract frontmatter, and a command provider to add a “Create new markdown file” button.
Full typings live in phials-plugin-example under sdk/plugin-types.generated.d.ts (and sdk/command-types.generated.d.ts for commands). This page is a conceptual map; use the linked guides for details and APIs.
See also: Plugin system overview · Getting started · Plugin API
The Toolkit
| Provider Type | What it does |
|---|---|
| Command | The engine for user actions (buttons, menus, shortcuts) |
| Preview | The canvas for file contents (thumbnails, viewers, editors) |
| Metadata | The intelligence layer (extracts data for columns, details) |
| View | The layout engine (custom file browser layouts) |
| Module | The workspace extension (custom dockable panels) |
| Theme | The paint (custom color palettes) |
command
Commands are the lifeblood of user interaction in Phials. Instead of writing separate, brittle code for a toolbar button, a context menu item, and a keyboard shortcut, you define a single, powerful Command.
You tell Phials what the command does (its action) and where it should appear by default (its defaultPlacements), and Phials handles surfacing it beautifully in the UI. The major benefit of this centralized approach is user customization: because actions are registered as commands, users can remap their keyboard shortcuts and customize exactly which app surfaces (PathBar, context menus, selection bar, header, command palette) the command appears on.
Additionally, commands are highly context-aware. Using when clauses or context keys, you can configure commands to intelligently match various app states and data—such as the currently selected file or folder, specific MIME types, or any arbitrary condition you define. They only show up when they’re actually useful.
Example: The official phials-plugin-example plugin registers a demo command (“Hello from community plugin”) in src/main.ts.
Guide: Command providers
preview
Preview providers let you teach Phials how to display specific types of files. Don’t let the name fool you: previews are not just read-only viewers—they are often full file editors or interactive utilities (as is the case with many of Phials’ built-in plugins).
You provide Svelte components, and Phials seamlessly uses them whenever the user encounters a matching file (matched by extension, MIME type, or custom logic). You can provide different components for different contexts: a small thumbnail for the grid view, a larger preview for the preview pane, and a fullscreen viewer. Note that a fullscreen preview inherently acts very much like a center-panel module, but is specifically bound to a file’s lifecycle.
Example: A plugin that adds previews for 3D models, providing an interactive WebGL viewer for the main pane and a rendered image for the thumbnail. Or a Markdown plugin that provides a split-pane editor and live preview.
Guide: Preview providers
metadata
Metadata providers are the intelligence layer of Phials. They extract structured data from files so Phials can display it, filter by it, and sort by it.
When a file is loaded, your provider can read its contents and return structured fields. This data automatically appears in the Details pane and becomes a first-class citizen in the app, usable as sortable columns in the list view. Multiple providers can match the same file, and Phials will intelligently merge the results.
Example: An image plugin that extracts EXIF data like focal length and camera model, or an audio plugin that extracts ID3 tags like artist and album. Suddenly, users can sort their entire music folder by bitrate.
Guide: Metadata providers
view
View providers let you completely reinvent how files are displayed in the main browser area.
While Phials comes with standard views like Grid and List, you can build custom layouts optimized for specific workflows. You provide a Svelte component that receives the current folder’s contents, and Phials adds your view to the view switcher.
Example: A Kanban board layout for task files, a calendar view for files with dates, a specialized “compact list” mode for developers, or a node-based graph view for a knowledge base.
Guide: View providers
module
Modules are custom, dockable panels that live alongside the main file browser, expanding what Phials can do without cluttering the core experience.
You provide a Svelte component, and users can open it in the sidebar, bottom panel, or center area. Modules are great for persistent tools that need to stay open while the user browses. (Note that while a center-area module looks similar to a fullscreen preview, modules are generally independent tools, whereas previews are always tied to a specific file.)
Example: A scratchpad for taking notes, a custom search interface, a system monitor, or a specialized inspector that updates as the user selects different files.
Guide: Module providers
theme
Theme providers add new color palettes to Phials. You define the CSS variables for light and/or dark mode, and your theme appears in the app’s theme picker.
Example: A high-contrast palette, a brand pack for a team, or a seasonal light/dark pair.
Guide: Theme providers
Related
- Public API contract — which types are stable in v1
- Community plugins — manifest and API limits for community bundles