Plugins overview

“Plugins” in Pylon means two concrete things — and neither is a manifest.plugins: [...] list. There is no such array today.

TS packages (@pylonsync/*) — installable npm packages that return a manifest fragment (entities, actions, queries, policies) plus handler factories. You compose the fragment into your buildManifest() call. Use these to add features the framework binary doesn’t already cover.
Built-in runtime plugins — a small set compiled into the pylon binary and wired automatically from your schema or environment. You don’t name them anywhere; they activate when the relevant signal is present (a tenantId field, a .owner() annotation, an env var).

Features that are built into the framework binary already (no package, no plugin needed):

API keys — /api/auth/api-keys routes for mint / list / revoke. See Auth → API keys.
TOTP / 2FA — /api/auth/totp/* routes for enroll / verify / disable + backup codes. See Auth → TOTP.
Transactional email — PYLON_EMAIL_PROVIDER env (sendgrid / resend / stack0 / webhook) + ctx.email.send(). See Integrations → email.
Audit log — /api/auth/audit + /api/auth/audit/tenant routes.
Organizations — Org / OrgMember / OrgInvite entities + /api/auth/orgs/* routes. See Auth → Organizations.

TS packages

Install with bun add, then spread the manifest fragment into buildManifest():

Package	Purpose
@pylonsync/stripe	Declarative billing — plans, checkout, portal, cancel/restore, signature-verified webhook, subscription entity.
@pylonsync/feature-flags	Local-eval flags — boolean + multivariate, percentage rollouts, targeting predicates, per-variant JSON payloads.
@pylonsync/webhooks	Outbound webhook delivery — Svix-compatible HMAC signatures, retry schedule, secret rotation.

Each package exports a factory (e.g. stripe({...}), webhooks({...})) that returns { manifest, handlers, ... }. Pylon loads function handlers one-per-file, so you also add one-line wrapper files under functions/ — see each package’s page for the exact list.

Built-in runtime plugins

These live in crates/plugin/src/builtin/ and are registered by the runtime at boot. They are auto-wired, not enabled through a manifest list.

Built-in	How it turns on	Reference
`tenant_scope`	Automatic on any entity with a `tenantId` field	Data hygiene
`owner_stamp`	Automatic on any field declared `field.X().owner()`	Data hygiene
`rate_limit`	Always on; tuned via `PYLON_RATE_LIMIT_MAX*` env	Security
`csrf`	Always on; allowlist from `manifest.auth.trustedOrigins` / env	Security
LLM proxy (`ai_proxy`)	Env-configured; powers `/api/llm/complete`, `/api/ai/stream`, `ctx.llm`	Search & AI
In-process cache	Internal; backs SSR / ISR response caching	—

How built-ins hook in

Built-ins observe the request and data path at fixed points. The exact Rust hooks (see Writing your own):

HTTP request
     │
     ▼
   on_request ──── rate_limit (reject if over budget)
     │       ──── csrf (origin check on cookie-authed writes)
     │
     ▼
   entity write (insert / update / delete)
     │   ──── before_insert / before_update / before_delete
     │        (tenant_scope injects + validates tenantId;
     │         owner_stamp stamps ownerId from the session)
     │
     ▼
   after_insert / after_update / after_delete

A built-in can inspect or reject a request (on_request), mutate or reject a write (before_*), react after a write lands (after_*), add HTTP routes (routes()), or contribute manifest entities (entities()).

There is no `plugins: []` array

Older drafts of these docs described enabling plugins through a pylon.manifest.json plugins list with per-plugin config. That mechanism does not exist. Built-ins are automatic; you influence them through your schema (add a tenantId field, annotate a field .owner()) and environment variables. App-specific cross-cutting logic goes in server functions and policies, not a plugin config block. pylon plugins list prints a roadmap catalog of plugin names (validation, slugify, versioning, cascade, MCP, and more). These are planned, not installable today — treat the list as a preview, not an API.

Plugins vs functions

Plugins / built-ins	Functions
Implicit — fire on every relevant op	Explicit — called by name
Auto-wired from schema/env, or composed from a TS package	Defined in TS files under `functions/`
Can mutate data in-flight (built-ins)	Run inside a transaction; return a result
Cross-cutting concerns (tenant scope, owner stamp, rate limit)	Business logic
Compiled into the binary, or shipped as a package	Hot-reloaded by the dev server

Use a built-in when the behavior should apply to every call. Use a function when callers opt in by name.

Writing your own

There is no dynamic plugin loading yet. To add a Rust built-in you build a custom runtime that registers it; for TypeScript-side logic, use functions and policies. The SDK ships a definePlugin({ name, entities, hooks }) helper, but the runtime does not consume its output yet. See Writing your own plugin for the real Plugin trait and the honest state of extensibility.

​TS packages

​Built-in runtime plugins

​How built-ins hook in

​There is no plugins: [] array

​Plugins vs functions

​Writing your own