Skip to content

Let users choose and read folders

Use api.files.pickDirectory() to ask the user for a folder, then api.files.readDirectory() to read its immediate entries.

The picker is always available. Reading the chosen folder requires filesystem.read, or filesystem.write, which includes the supported read operations.

Declare read permission

{
"permissions": ["filesystem.read"]
}

Choosing a folder does not grant a temporary per-folder permission. The manifest permission gates the Plugin API call, and the operating system can still reject a location Phials cannot read.

Ask and read

async function chooseSourceFolder(
api: PluginAPI,
): Promise<{ path: string; entries: readonly FileEntry[] } | null> {
const path = await api.files.pickDirectory({
title: "Choose a source folder",
});
if (path === null) return null;
const result = await api.files.readDirectory(path);
return { path, entries: result.entries };
}

null means the user cancelled. Cancellation is an expected outcome, not an error and not a reason to show a warning.

Supply initialPath when your plugin has a relevant existing location:

const path = await api.files.pickDirectory({
title: "Choose an export folder",
initialPath: lastExportFolder,
});

Do not invent a fallback path when the user cancels.

Understand the listing

readDirectory(path) is shallow. It returns the immediate children plus any typed failures encountered while materializing individual children; it does not recursively scan descendants.

const result = await api.files.readDirectory(path);
const entries = result.entries;
const folders = entries.filter((entry) => entry.is_dir);
const markdownFiles = entries.filter(
(entry) =>
entry.is_file &&
api.files.getExtension(entry.name) === "md",
);
for (const failure of result.failures) {
api.notify.warning(
`Could not inspect ${failure.path ?? "one child"}: ${failure.code}`,
);
}

The result is a filesystem listing, not the current Explorer projection. It does not automatically adopt the user’s Explorer search, filter, sort, hidden-file, or folders-first settings. Sort only when your task needs a defined order:

const byName = [...entries].sort((a, b) =>
a.name.localeCompare(b.name, undefined, {
numeric: true,
sensitivity: "base",
}),
);

For a file-view component, consume the pane’s current listing instead of calling readDirectory again. See Render files, selection, and navigation.

Handle read failures

Reads can fail because the folder moved, a network volume disconnected, permissions changed, or the operating system denied access.

type FolderLoadResult =
| { status: "loaded"; entries: FileEntry[] }
| { status: "failed"; message: string };
async function loadFolder(
api: PluginAPI,
path: string,
): Promise<FolderLoadResult> {
try {
return {
status: "loaded",
entries: (await api.files.readDirectory(path)).entries,
};
} catch (error) {
const message =
error instanceof Error ? error.message : "Unknown filesystem error";
api.notify.error("Could not read the selected folder.");
return { status: "failed", message };
}
}

Do not report an empty listing when the read actually failed. In a persistent interface, model loading, empty, and error as separate states.

Avoid recursive fan-out

Do not implement an unbounded recursive scan by calling readDirectory for every folder in parallel. It can overwhelm slow, remote, removable, or synchronized filesystems and is not a supported substitute for a purpose-built capability.

If your task requires a known bounded walk:

  • ask the user for the root
  • define an explicit depth or item limit
  • limit concurrency
  • skip broken links
  • allow cancellation
  • report unreadable subfolders separately

The typed API grants only the operations it exposes. It does not imply an unrestricted recursive filesystem API.

SDK reference

This article includes AI-assisted content.

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