v0.1.0
/
Bun-first BFF core
Thin BFF kernel for frontend-owned backends
Build a small BFF on Bun without dragging in a full backend framework.
`humming` keeps the core deliberately narrow: `health`, `options`, and `forward`. Everything else stays composable through plugins, hooks, and explicit runtime configuration.
Bun-first
Plugin-first
CLI included
Transport-aware forward
Quick start
bunx humming init my-bff --template with-forward
cd my-bff
bun install
bun run devWhat you get
+ health endpoint
+ options routes
+ forward rules
+ plugin-ready app shell
Core stays small
Keep `health`, `options`, and `forward` in core and move optional behavior into plugins.
Scale by composition
Add auth, cache, metrics, rate limit, or custom routes only where the project actually needs them.
Where it fits
Built for thin BFFs, local proxy layers, and frontend teams that want control.
Good fit
- project-level BFFs
- local routes and small aggregations
- upstream forwarding with explicit hooks
- frontend-owned runtime extensions
Not trying to be
- a full API gateway
- a heavy backend application framework
- a hidden-convention platform
- an everything-in-core runtime
Key runtime ideas
- plugin-first extension model
- explicit forward transport strategy
- shared services across plugins
- small surface area with readable behavior
Use cases
Use it where teams need a thin edge layer, not a giant backend surface.
Ship a small backend the frontend team can actually maintain.
Add local routes, option endpoints, auth guards, and upstream forwarding without pulling the project into a controller-heavy backend stack.
Replace ad hoc dev proxy files with something operationally clearer.
Keep request shaping, transport selection, metrics, and runtime hooks in one readable service that still feels lightweight.
Expose a few composed endpoints without pretending this is a giant platform.
Start with small aggregation and request rewriting work close to the UI, then grow through plugins only where the project really needs it.
Give multiple projects the same BFF baseline without copying proxy glue everywhere.
Use the CLI, examples, and official plugins to standardize a small but consistent runtime across apps.
Core surface
Three built-ins, then extension points.
Simple runtime health endpoint that stays public and predictable.
Serve dictionaries and option data from static or HTTP-backed providers.
Shape and proxy upstream requests with route rules, hooks, and transport strategy selection.
client
→
humming core
→
plugins
→
upstream services
Why this shape
Sits between a temporary proxy file and a heavyweight backend platform.
Fast to start, easy to outgrow.
Good for a quick local redirect, but it usually stops short of shared plugins, explicit runtime services, transport policy, and observability.
A small kernel with enough structure to stay readable.
Keep the core narrow, grow through plugins, and make route, forward, and runtime behavior visible enough that teams can actually maintain it.
Broader surface, more ceremony, different job.
Useful when the service itself is the full backend platform, but often more infrastructure and abstraction than a thin frontend-facing BFF needs.
Plugin ecosystem
Grow outward from a stable kernel instead of stuffing optional behavior into core.
Official plugins
Auth
Protect routes with bearer checks, JWT validation, and role-based rules.
Cache
Cache eligible responses with memory or Redis-backed stores.
Metrics
Expose Prometheus-style request metrics close to the BFF edge.
Rate limit
Enforce request ceilings per route, user, or custom key strategy.
CORS
Handle browser-facing preflight and cross-origin policy cleanly.
Options
Register static and HTTP-backed option sources without cluttering app code.
Extension strategy
Start with official building blocks
Use the shipped plugins for common operational needs instead of inventing one-off middleware in every project.
Add custom project plugins
Register local routes, middleware, option sources, and forward hooks through the same explicit runtime model.
Leave room for a future ecosystem
`humming` is already shaped for external plugins and presets, but the kernel stays small so the ecosystem can grow without making core fuzzy.
core
→
official plugins
→
custom plugins
→
future presets
CLI
Go from empty folder to a working BFF skeleton in one command.
Scaffold
bunx humming init acme-bff --template with-plugins
Created acme-bff with the "with-plugins" template.
Next steps:
cd acme-bff
bun install
bun run devTemplate shape
acme-bff/
src/
main.ts
package.json
README.md
.env.exampleTemplates
basic
Smallest useful app with core built-ins only.
with-plugins
Auth, cache, metrics, rate limit, options, and a custom plugin route.
with-forward
Forward rules plus request and response hook examples.
Runnable paths
Jump from the product story into concrete, runnable examples.
basic
Core only
Start with health and options only when you want the smallest useful app shape.
with-pluginsOperational add-ons
See auth, cache, metrics, rate limiting, request logging, and options in one app shell.
with-forwardForward and hook flow
Use request and response hooks plus transport-aware forwarding when the BFF needs upstream control.
with-async-pluginAsync startup
Reach for `createApp()` when plugin setup needs async work before the app is ready.
Documentation
Start from the entry that matches the job at hand.
Docs portal
Single entry point for overview, plugin system, CLI, transport, production, and benchmark guides.
Overview
Positioning, architecture boundaries, and how the core is meant to stay small.
Transport
Keepalive, retry policy, and custom transport strategy boundaries.
CLI
Scaffold a new app quickly with the Bun-first starter templates.
Runtime signals
Small runtime does not have to mean opaque runtime.
`humming` is trying to stay small without forcing teams to debug blind. Startup summaries, forward timings, hook ownership, transport strategy, and plugin cleanup are meant to stay visible as the app grows.
Startup summaries
See which plugins were enabled and what each one registered during setup.
Forward phase timing
Split matching, hooks, upstream execution, and error handling into separate timing phases.
Hook ownership
Track which plugins contributed the active forward hook chain for a request.
Explicit teardown
Dispose plugin resources cleanly instead of letting timers, clients, and shared handles leak into shutdown.
Transport and operations
The runtime is small, but the operational surface is still intentional.
`humming` keeps `forward` in core because upstream control is a real BFF concern. That means transport policy, rollout boundaries, regression baselines, and observability deserve first-class guidance instead of scattered notes.
Transport
Choose between baseline fetch, keepalive-oriented fetch, retrying fetch, or a custom transport contract.
Production
Read the deployment model, forward safety stance, metrics guidance, and cache and auth boundaries.
Benchmark
Compare direct upstream traffic against forwarded traffic before you change runtime behavior.
Roadmap
See where plugin lifecycle, observability, and broader platform maturity are heading next.
Start here
If your team wants a thin BFF with clear boundaries, this is the point of entry.
Read the docs, inspect the examples, and scaffold a starter app. The project is intentionally trying to stay small enough that you can understand the runtime before the day is over.