pi-extension-settings SDK

A type-safe, declarative settings management SDK for pi extensions. Define your schema once — get typed accessors, validation, autocompletion, live updates, and a rendered settings panel for free.

Why this SDK?

Most extensions need settings. Most extensions end up writing the same plumbing: storage, validation, change events, UI wiring, and a set of TypeScript types that drift from the storage format over time.

This SDK removes all of that. You write one schema and get:

| Without the SDK | With the SDK | | ----------------------------------------------- | -------------------------------------------------- | | Hand-rolled storage keys and JSON parsing | settings.get("key") returns the right type | | Manual validation scattered across the codebase | One validation field per node | | UI boilerplate for every new setting | A settings panel rendered automatically | | Silent type drift between storage and code | InferConfig<T> enforces the type at compile time | | Wire listeners by hand, remember to clean up | onChange(), session-scoped, no cleanup required |

Feature highlights

• End-to-end type safety. InferConfig<T> derives a flat key → value map from your schema. Every get(), set(), and onChange() is type-checked against that map.
• Declarative schema. One call to S.settings({...}) describes defaults, validation, transformation, autocompletion, and display format.
• Rich node types. Text, Boolean, Enum, List (structured rows), Dict (key/value pairs), and Section (nestable groups).
• 20 validators, 16 transforms, 2 completers, 5 display functions out of the box. Compose them with v.all, v.any, t.pipe, t.compose.
• Live updates. Subscribe to per-key events with onChange(). Session-scoped — no listener cleanup required.
• Strict runtime checks. S.settings() validates tooltip length and enum defaults at construction time, so schema bugs fail fast.
• Renders on GitHub and GitBook. Documentation is pure CommonMark with Mermaid diagrams — no platform lock-in.

Architecture at a glance

flowchart LR
    Schema["Schema<br/>(S.settings)"] --> ES["ExtensionSettings"]
    ES --> Storage[("Storage")]
    ES --> Panel["Settings Panel<br/>(auto-rendered)"]
    Panel -- "user edits" --> ES
    ES -- "onChange event" --> Ext["Your extension"]
    Ext -- "settings.set()" --> ES
    Ext -- "settings.get()" --> ES

Your extension never touches storage directly. It talks to ExtensionSettings, which brokers reads and writes, fires change events, and keeps the UI synchronized.

60-second example

import { S, ExtensionSettings } from "pi-extension-settings/sdk";
import { v, t, d } from "pi-extension-settings/sdk/hooks";

// 1. Declare the schema
const schema = S.settings({
  "api-url": S.text({
    tooltip: "API base URL",
    default: "https://api.example.com",
    validation: v.url(),
    transform: t.normalizeUrl(),
  }),
  theme: S.enum({
    tooltip: "Color theme",
    default: "dark",
    values: ["dark", "light", "system"],
  }),
  enabled: S.boolean({
    tooltip: "Enable extension",
    default: true,
  }),
});

// 2. Create the accessor
const settings = new ExtensionSettings(pi, "my-extension", schema);

// 3. Read — fully typed
const url = settings.get("api-url"); // inferred as string
const on = settings.get("enabled"); // inferred as boolean

// 4. Write — fully typed
settings.set("theme", "light"); // ok
// settings.set("theme", 42);          // compile error

// 5. React to changes
settings.onChange("theme", (t) => applyTheme(t));

Tip: The settings panel UI is generated from your schema automatically. You do not write any UI code.

Documentation map

Get going

| Page | What you'll learn | | --------------------------------------- | --------------------------------------------------------------------- | | Getting Started | Install the SDK and ship your first integration in under five minutes |

Concepts

| Page | What you'll learn | | ----------------------------------------------------- | -------------------------------------------------------- | | Concepts Overview | The three core abstractions and how they fit together | | Schema Builder | The S namespace, runtime validation, and InferConfig | | Node Types | Every node type, field by field, with a decision tree | | ExtensionSettings | Class lifecycle, get / set / onChange / getAll |

Hooks

| Page | What you'll learn | | --------------------------------------- | ------------------------------------------------------------- | | Hooks Overview | The four namespaces, execution order, composition | | Validators | All 20 built-in validators with examples | | Transforms | All 16 built-in transforms with examples | | Completers | c.filePath and c.staticList | | Display Functions | d.color, d.badge, d.path, d.dictEntry, d.keybinding |

Examples

| Page | Complexity | What it shows | | ---------------------------------------------- | ------------ | ----------------------------------------------------- | | Weather Widget | Beginner | Text, Boolean, Enum; basic validators | | Code Formatter | Intermediate | Sections, List with Struct, numeric validation | | AI Assistant | Advanced | Nested sections, Dict, InferConfig, full hook stack |

Reference

| Page | Use when | | ---------------------------------------- | ------------------------------------------------- | | API Reference | You want the full list of exports at a glance | | Type Reference | You need the exact TypeScript signature of a type | | Error Reference | You need to catch a specific error class |

Quick links

• Landing an extension? Start with Getting Started.
• Already know the basics? Jump to the API Reference.
• Looking for a specific hook? Try the Hooks Overview.
• Debugging a runtime error? See the Error Reference.

Documentation drafted with AI assistance — Claude Opus 4.6 (Anthropic). Reviewed by a human maintainer before publishing.