Getting Started

This guide walks through authoring a plugin using the public phials-plugin-example repository: a Vite + Svelte 5 + TypeScript project, phoundry-ui, a demo plugin, and a TypeScript SDK in sdk/ that matches the API Phials exposes to plugins.

Read first: Public API contract (trust model, versioning, permissions). API details: Plugin API and lifecycle. Install and manifest: Community plugins.

Clone the example repository

git clone https://github.com/phoundry/phials-plugin-example.git
cd phials-plugin-example
npm install

Project layout (authoring)

Path	Purpose
`sdk/phials-plugin-sdk.d.ts`	Triple-slash barrel — reference this (or individual `sdk/*.generated.d.ts`) for types
`sdk/manifest-schema.ts`	Manifest parsing / validation helpers aligned with Phials
`public/manifest.json`	Authoring-time manifest; copied into `dist/` by the build
`src/main.ts`	Default export: factory returning a `PhialsPlugin`

Full field lists for PhialsPlugin, PluginAPI, providers, and commands are in sdk/*.generated.d.ts — browse them in your editor or on GitHub.

Build and validate

npm run build
npm run validate

validate checks manifest shape, id/version semver rules, and that dist/manifest.json, dist/main.js, and optional dist/styles.css exist.

Release artifact shape

Phials expects exactly these files next to each other (for example as GitHub Release assets):

File	Required
`manifest.json`	Yes
`main.js`	Yes (ES module; default export is a function that returns `PhialsPlugin`)
`styles.css`	No

Keep plugin.id stable across releases. Use semver for version, and set minAppVersion / optional pluginApiVersion per the contract.

Local testing in Phials

Build the example (or your fork) so dist/ contains the files above.
In Phials, open Settings → Plugins → Community plugins.
Community plugins safe mode is on by default. You must turn it off and accept the warning before you can browse the index, install, or enable community plugins. With safe mode on, already-installed community plugins are also disabled.
Install or load your bundle using whatever control your Phials version exposes (index entry, local path, or release URL).

Details of manifest fields, permissions, updates, and permission review are in Community plugins.

Publish a GitHub Release

Tag a semver release on your plugin repository.
Attach manifest.json, main.js, and styles.css (if any) as release assets with those exact filenames.
Ensure repository (and related fields) in the manifest match the repo users and the registry expect.

Submit to the community registry

The public index is github.com/phoundry-lab/phials-plugins. Before opening a PR, run npm run validate in that repo and follow SUBMISSION.md. Governance and removals: POLICY.md. Your manifest id must match the registry entry; release assets must match Community plugins.

Scoped styles

Prefer Svelte component <style> so rules are scoped by default. Global CSS in styles.css can affect the whole app — keep it minimal and documented. See the public API contract for expectations.

Breaking API changes

When a new phials-plugin-example (or sdk/) release changes types, update your dependency or copy of sdk/, fix compile errors, bump pluginApiVersion / minAppVersion as needed, and ship a new semver plugin release. See Versioning and compatibility in public-api-contract.md.

Deprecated provider types

New work should use CommandProvider with defaultPlacements instead of legacy toolbar, context, or selection providers. Migration notes live in the per-type guides under types/.