Read Phials app settings
Use api.appSettings when a plugin presentation should follow a supported Phials preference. The projection is intentionally read-only and smaller than the complete app configuration.
interface ReadonlyAppSettings { readonly thumbnailsEnabled: boolean; readonly thumbnailSize: number; readonly thumbnailQuality: number; readonly showHiddenFiles: boolean; readonly showParentDirectory: boolean;}These values have app-wide meaning:
| Setting | Use |
|---|---|
thumbnailsEnabled |
Whether thumbnail presentation is enabled globally |
thumbnailSize |
Current owning-Host generation size preference; display size is independent |
thumbnailQuality |
Current owning-Host generation quality preference |
showHiddenFiles |
Whether dot-hidden entries may appear in Explorer listings |
showParentDirectory |
Whether Explorer listings include the .. parent entry |
The Explorer pane already applies hidden-file and parent-entry settings to pane.listing.entries. A file view should render that listing rather than filter it again. Read the settings directly when building another presentation that genuinely needs to mirror the global choice.
Read settings at the point of use
Retain the PluginAPI during activation, then read its app settings in a command or provider callback:
import { getPluginAPI } from "./runtime";
function showHiddenPreference() { return getPluginAPI().appSettings.showHiddenFiles;}Each property is a live getter. Read it when the work runs rather than copying all values during activation.
Respond reactively in Svelte
Read app settings inside $derived when a mounted component should update with Phials settings:
<script lang="ts"> import { getPluginAPI } from "./runtime";
const appSettings = getPluginAPI().appSettings;
const showHidden = $derived(appSettings.showHiddenFiles);</script>
<p>{showHidden ? "Hidden entries are included" : "Hidden entries are hidden"}</p>Keep the getter read inside the reactive expression. This captures only a snapshot:
const { showHiddenFiles } = getPluginAPI().appSettings;The local number will not change later. Destructuring is fine for one operation, but not for a long-lived reactive presentation.
Outside Svelte, read the property again when an event, command, or request runs. ReadonlyAppSettings does not expose a mutation method or promise to notify arbitrary long-lived services.
A Thumbnail renderer reads context.generation, captured context.settings and declared context.variants. It must not construct an independent request from these live preferences or read ambient values mid-render. Phials applies current Host generation policy and controls whether Thumbnail demand is presented. See Add thumbnails and toolbar controls.
Do not mutate global preferences
The following is outside the plugin contract:
// Not supportedapi.appSettings.showHiddenFiles = true;Do not invoke configuration commands, edit Phials configuration files, or recreate a global setting under your plugin’s control. If the user needs to change a Phials preference, explain where it lives in Phials settings.
Choose the correct state owner:
| Value | Owner |
|---|---|
| Supported global Phials preference | api.appSettings |
| User-configurable plugin behavior | api.settings |
| Pane view, selection, navigation, or saved-view state | PluginPaneContext |
| Internal plugin application data | api.storage or api.database |
For example, “show review badges” is a plugin setting. The current Explorer item size is pane view state. Whether Phials globally enables thumbnails is an app setting.
If the global preference you want is not in ReadonlyAppSettings, design a plugin-owned setting or file a public-SDK proposal. Do not read undocumented runtime fields.
Next, learn when and how to call an approved host command.