Elpod Documentation: Modular Elysia Applications on Bun

Experimental / working alpha: Elpod is early-stage. APIs and conventions may change between versions. Pin Elpod and Bun versions in production, read the changelog before upgrades, and run elpod audit and elpod doctor in CI.

Elpod is an early-stage, decorator-free application framework for modular Elysia applications on Bun. It adds explicit constructor dependency injection, feature boundaries called pods, provider lifetimes, lifecycle management, and architecture checks. Controllers register native Elysia routes; Elpod does not replace Elysia’s router.

Use Elpod when an Elysia backend has enough services and teams that dependency ownership and feature boundaries need to be visible. For a small service that does not need those conventions, plain Elysia keeps the application simpler. Start with a runnable feature, then read dependency injection and feature pods.

The core composition model, native controller routes, request scopes, typed configuration, structured errors, lifecycle handling, health routes, route inspection, and vendor-neutral observability boundaries are solid today. Database drivers, durable queues and event brokers, distributed cache and rate limiting, telemetry SDK/exporter setup, identity providers, and deployment hardening remain application-owned adapters or planned work. Treat the framework as a set of explicit boundaries, not a guarantee that your application is secure or distributed by default.

Choose a path

This guide teaches the “why” before the “how”. Every page starts with the idea a feature solves, then shows Elpod’s small mechanism for solving it, and ends with the boundary Elpod deliberately leaves to your application.

The Elpod tour

If you want the scenic route, take the ship around in this order:

1. Launchpad — Getting started: get a tiny service in orbit.
2. Neighborhoods — Features and pods: give each product idea a home.
3. Toolbelt — Dependency injection: bring collaborators in openly.
4. Airlocks — Providers and boundaries: decide what may cross a feature boundary.
5. Bridge — Routing and controllers: let native Elysia handle HTTP.
6. Flight systems — Errors, health, and observability.
7. Fleet operations — Security, testing, and deployment.

• New to Elpod: Getting started, then Features and pods and Dependency injection.
• Designing a larger service: Project structure, Providers, uses, exports, and imports, then Routing and controllers.
• Hardening a service: Errors, Health and shutdown, Observability, Security overview, and Deployment.
• Building async workflows: Events, Jobs, and Cache and locks.
• Looking up a feature: use the CLI, OpenAPI and routes, Testing, or Glossary.
• Choosing an approach: compare Elpod and plain Elysia or Elpod and NestJS.

Documentation map

Foundations

Getting started · Project structure · Features and pods · Dependency injection · Providers and boundaries · Routing · Plugins · Configuration

Runtime capabilities

Errors · Cache and locks · Events · Jobs · HTTP client · Observability · Health and shutdown · OpenAPI · Testing

Security

Security overview · Authentication · Sessions · CORS and CSRF · Rate limiting · Brute force and signed URLs · Tenancy · Policies

Operations

CLI · Deployment · FAQ · Glossary

All application examples use Bun ESM and import the public package: import { ... } from "@elpod/core".