Vite+ Pi Extension Template

A small, public-package-ready template for building a Pi extension with TypeScript, Vitest, and Vite+. It includes a minimal /greet slash command, a TypeBox-backed greet tool, a shared pure helper, tests, Forgejo CI, and a Nix/devenv development environment.

Pi loads TypeScript extensions directly, so this package intentionally publishes its source instead of creating a compiled build.

Requirements

• Nix with flakes enabled
• devenv
• Pi for interactive testing
• A package manager supported by Vite+ (pnpm is pinned through packageManager)

Setup

devenv shell
pnpm install

Try the extension

Launch Pi with the source entry point:

pnpm run dev

Run /greet Ada to exercise the command. The agent can call the greet tool with a name to exercise the tool registration.

For package-style local installation instead:

pi install ./

Pi packages execute with the user's full system permissions. Review extensions before installing them.

Development

The extension entry point is src/index.ts. Both extension surfaces use the pure createGreeting helper from src/greeting.ts:

• /greet [name] displays a notification and defaults to world.
• greet accepts a required name parameter and returns a greeting plus structured details.

Run the test suite once or in watch mode:

pnpm run test
pnpm run test:watch

Quality checks

Vite+ provides formatting, linting, type checking, and the Vitest runner:

pnpm run check
pnpm run lint
pnpm run fmt
pnpm run test:coverage

Coverage reports are written to coverage/. Validate the exact npm package contents without publishing:

pnpm run pack:check

Only src/, README.md, LICENSE, and package metadata are included in the published package. Pi's core @earendil-works/pi-coding-agent and typebox packages are peer dependencies; matching development dependencies make their APIs available locally.

Customize the template

Before publishing your own extension:

1. Rename the package and update its description, author, repository, and keywords in package.json.
2. Replace the greeting helper, command, and tool in src/.
3. Update the tests and this README for the new behavior.
4. Keep runtime third-party packages in dependencies. Keep Pi-provided core packages in peerDependencies with a "*" range.
5. Run pnpm run check, pnpm run test:coverage, and pnpm run pack:check.

Publish through your configured npm registry when ready:

pnpm publish

Consumers can then install the package with Pi:

pi install npm:vite-pi-extension

License

MIT