Introduction to Efesto

Efesto is a filesystem-routing framework for building documented, type-safe HTTP APIs. You create a file, Efesto turns its location into a route, and your schemas become both validation and OpenAPI documentation. It runs on two stacks:

• Express (efesto) — the original stack. Service classes with _get/_post methods, OpenAPI written to generated .yaml files, validation through express-validator, and a TypeScript type-generation system that can edit your service files in place.
• Bun / Elysia (efesto/elysia) — a separate entrypoint. Routes are idiomatic, native Elysia (or Efesto's optional BaseApiService class), validation and OpenAPI come from TypeBox natively.

Both stacks share one idea: the file path is the route. routes/user/index.ts serves /user, routes/user/[id].ts serves /user/:id.

Choose your stack

	Express (efesto)	Bun/Elysia (efesto/elysia)
Runtime	Node.js + Express	Bun + Elysia
Route file	class extends BaseApiService	native Elysia instance or class extends ApiService
Handler	_get(req, res, next)	(ctx) => value
Validation	express-validator (_<m>Validation)	TypeBox schema (body/query/params)
OpenAPI	generated .yaml + Magic Types	native @elysiajs/openapi from TypeBox
Types	generated .d.ts (+ in-place editing)	inferred natively by TypeScript
Status	stable	beta

If you have an existing Node/Express app, use the Express stack. If you are starting on Bun, use the Elysia stack. The concepts (filesystem routing, ABAC permissions) carry across; the implementation differs, and every guide shows both with tabs.

What Efesto gives you

• Filesystem routing — folders and [param] files map to paths and route params.
• Schema-driven OpenAPI — document an endpoint where you write it; Efesto emits the OpenAPI document.
• Magic Types (Express) — write string::email! instead of a verbose schema object. See Magic Types.
• Type generation (Express) — keep TypeScript types in sync with your schemas, optionally rewriting your method signatures for you. See Type Generation.
• ABAC — declare permission: [action, model] on an endpoint; Efesto checks it against a CASL ability you provide. See ABAC Permissions.
• Hooks, not lock-in — authentication, error handling, caching, and file uploads are thin integrations around standard tools (express-validator, Multer, Redis), not bespoke subsystems.

What Efesto is not

Efesto wires hooks; it does not implement auth strategies, cloud storage, rate limiting, or a caching framework. Those live in your code, using the libraries you choose. Each guide is explicit about where the framework stops and your code begins.

Start with Installation.