Skip to content

Documentation · IGNIS

Philosophy ​

A REST API that grows past a handful of endpoints needs somewhere for its code to live: how classes find each other, where data access sits, how a route is validated and documented. IGNIS answers that on top of Hono. Structure - dependency injection, a layered shape, generated OpenAPI docs - is part of the framework, so each team doesn't invent its own.

What IGNIS gives you ​

  • A standalone dependency injection container (@venizia/ignis-inversion), with @inject, singleton and transient scopes, and constructor injection. It is a small package with one dependency, reflect-metadata, and it imports nothing else from IGNIS.

  • A layered shape: Controller -> Service (optional) -> Repository -> DataSource -> a database. The database is PostgreSQL (three drivers, PGlite included) or SQLite. Search engines (Typesense, Meilisearch) and a browser-side HTTP connector plug in behind the same repository contract.

  • Request validation and OpenAPI docs generated from the same Zod schema, so they can't drift apart.

  • A decorator-driven artifact system. @controller, @service, @repository and @datasource mark your classes, and the application registers them at boot, before preConfigure(). You pick how the list is built:

    • ignis-artifacts generate writes an index file at build time. It needs no plugin, and ignis-artifacts check fails CI when the file is stale.
    • @venizia/ignis-boot/auto needs no file. A Bun plugin scans src when the application starts (the first start parses the sources; the result is cached, so later starts skip the scan) and inlines the list when you build a binary.

    Neither mode enforces a file-naming convention. See Bootstrapping.

  • Access control in the repository, not in each route: a row scope with a write guard, query defaults, and a CRUD controller that refuses to boot when a write route would inherit a read-only authorize. See What IGNIS offers today.

IGNIS aims for guided flexibility: sensible conventions, with an override for every one of them.

Performance ​

IGNIS runs on Hono, so routing and middleware are Hono's. The repository holds no benchmark, so this page states no throughput, startup or memory figures. Measure your own workload before you decide; the layers above Hono (injection, validation, repositories) cost something that depends on what your endpoints do.

What IGNIS is built on ​

ProjectWhat IGNIS uses it for
HonoThe HTTP engine: routing, middleware, Context, request IDs; served by Bun.serve
@hono/zod-openapi and ZodRoute definitions, request validation, the OpenAPI document
Drizzle ORMTable schemas, SQL, relations, and Zod schemas from tables (drizzle-zod)
CasbinPolicy enforcement for authorization (optional peer)
joseJWT signing and verification, JWKS
Scalar and Swagger UIThe API reference page (optional peers)

Runtimes ​

WhereRuntime
Server (@venizia/ignis)Bun >= 1.4
inversion, filter, kernel, worker, and connectors without a database driverAlso a browser or Web Worker
helpersThe root is server-only; /core, /common, /uuid, /temporal and /socket-io/client run in a browser

A browser entry bundles with plain vite build, no Node polyfill. The CI purity gate fails when an entry reaches a Node builtin. See Using IGNIS in a Browser or Web Worker.

What IGNIS offers today ​

The 0.4 line added the pieces a multi-tenant API needs. Each links to its guide or changelog.

NeedWhat IGNIS gives you
Keep a caller inside its own rowsAn access scope on the model; creates and updates are checked against it, and shared rows need write.sharedRows (Model settings)
Default filters and limits per modelquery.filter and query.limit in the model settings
Safe CRUD controllersCrudControllerFactory.build refuses to boot when a listed write route would inherit a read-only authorize
Scoped searchSearchControllerFactory.build({ scope }) applies the scope on the server
Clean shutdowninstallShutdownSignals() stops the application on SIGTERM and SIGINT
Code in a browser or workerThe browser-pure entries and the worker package

Maturity, honestly ​

AspectState
First npm releaseDecember 2025
Version line0.4, pre-1.0: a patch release can carry a breaking change, labeled in the changelog with how to migrate
Production readyEarly stage
BackingIndependent
ComponentsBuilt in: authentication, API reference, health check, mail, request tracker, socket.io, static assets, WebSocket
Community packagesFew
LTSNone yet

The framework is young. Expect the API to keep moving until 1.0.

When to use IGNIS, and when not to ​

SituationVerdictWhy
Medium API, 10-100 endpointsYesStructure prevents spaghetti code
Any team size, solo to largeYesThe same patterns scale either way
Want dependency injection with a small containerYes@venizia/ignis-inversion stands alone
Need a database, auth, and OpenAPI docsYesAll built in, ready to use
Bun-first developmentYesNative Bun support, single-binary builds
Growing out of a plain Hono projectYesSame foundation, incremental migration
3-5 endpoints, solo developerMaybeStart with Hono; migrate later if it grows
Quick prototype or MVPNoPlain Hono gets you to a first endpoint faster
Simple proxy or webhook handlerNoThe structure is overhead you don't need

Plain Hono is also the better fit when you're learning web development from scratch or deploying to the edge, where every millisecond of cold start counts.

What's still forming ​

Choosing IGNIS today trades a mature ecosystem for early access to a structured server framework. You get the dependency injection container, the repository pattern, Zod validation, and OpenAPI docs generated from the same schemas. IGNIS apps also compile to a single executable with Bun.

What you don't get yet: a large plugin ecosystem, extensive community packages, or a formal LTS release.

Next steps ​

  1. Check prerequisites - install the required tools.
  2. Complete the installation - build your first endpoint.
  3. Build a CRUD API - build a complete API.