Skip to content

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 supported
api.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.

This article includes AI-assisted content.

Documentation is licensed under CC BY 4.0. Phoundry names and marks remain reserved.