Plugins
Extend Katman with CORS, distributed tracing, structured logging, rate limiting, and more.
Katman plugins are just regular middleware and hooks. There is no special plugin API — a "plugin" is a guard, a wrap, or a set of lifecycle hooks that someone has packaged up for reuse.
All plugins ship as subpath imports from the katman package. You only import what you use, and unused plugins add zero bytes to your bundle.
You can build your own plugins the same way. A guard that checks a feature flag, a wrap that logs slow queries, a set of hooks that track metrics — they all follow the same patterns described in the Middleware and Server docs.
CORS
Cross-origin headers — static origin, origin list, or dynamic matching with a function.
OpenTelemetry
Distributed tracing — each procedure call becomes a span with error recording.
Pino Logging
Structured request logging — request received, response sent, errors caught.
Rate Limiting
Sliding window rate limiter — in-memory or pluggable backend (Redis, Upstash, etc.).
Body Limit
Reject oversized request bodies — returns 413 Payload Too Large.
Strict GET
Enforce GET-only access on query procedures — CSRF prevention.
Cookies
Read, set, and delete cookies inside procedures — secure defaults.
Compression
Gzip/deflate response compression hints for custom servers.
Signing & Encryption
HMAC-SHA256 signing and AES-256-GCM encryption via Web Crypto API.
Smart Coercion
Convert string query parameters to numbers, booleans, and null automatically.
Server Batch
Handle multiple RPC calls in one HTTP request — pairs with client BatchLink.
Publisher/PubSub
Event pub/sub — publish from mutations, subscribe via SSE. Memory or Redis backend.
Custom Serializers
Extend JSON for custom types — Date, BigInt, or your own classes.
Plugin types at a glance
| Plugin | Type | How to use |
|---|---|---|
| CORS | Header helper | Call corsHeaders() to get a headers object |
| OpenTelemetry | Wrap middleware | Add otelWrap(tracer) to a procedure's use array |
| Pino Logging | Lifecycle hooks | Pass loggingHooks({ logger }) to the hooks option |
| Rate Limiting | Guard middleware | Add rateLimitGuard(...) to a procedure's use array |
| Body Limit | Guard middleware | Add bodyLimitGuard(...) to reject oversized payloads |
| Strict GET | Guard (singleton) | Add strictGetGuard to enforce GET on queries |
| Cookies | Helper functions | Use getCookie(), setCookie(), deleteCookie() |
| Compression | Wrap middleware | Add compressionWrap() for gzip/deflate hints |
| Signing | Helper functions | Use sign(), unsign(), encrypt(), decrypt() |
| Smart Coercion | Guard (singleton) | Add coerceGuard to auto-convert string inputs |
| Server Batch | Handler factory | Use createBatchHandler() for batch endpoint |
| Publisher/PubSub | Event system | Use createPublisher() + MemoryPubSub or Redis |
| Custom Serializers | Helper | Use createSerializer() for custom JSON types |
What's next?
- Middleware — understand guards and wraps, which power most plugins
- Server — lifecycle hooks, which power the logging plugin