:fire: IGNIS

Enterprise-grade TypeScript server infrastructure built on Hono.

Package	Latest Version	Next Version
@venizia/ignis
@venizia/ignis-boot
@venizia/ignis-inversion
@venizia/ignis-helpers
@venizia/dev-configs
@venizia/ignis-docs

Ignis brings together the structured, enterprise development experience of LoopBack 4 with the blazing speed and simplicity of Hono -- giving you the best of both worlds. Think LoopBack 4's decorator-driven DI, repository pattern, and component system, running on Hono's ~140k req/s engine with Drizzle ORM's type-safe SQL.

Getting Started • Documentation • Examples • Contributing

Table of Contents

• Key Features
• When Should You Use Ignis?
• Framework Comparison
• Monorepo Packages
• Prerequisites
• Installation
• Quick Start
• Architecture Flow
• Application Lifecycle
• Built-in Components
• Helpers Ecosystem
• Project Structure
• Monorepo Development
• Examples
• FAQ
• Documentation
• Contributing
• License

Key Features

• High Performance -- Built on Hono, one of the fastest web frameworks (~140k req/s on Bun)
• Enterprise Architecture -- Layered architecture with Controllers, Services, Repositories, and DataSources
• Dependency Injection -- Lightweight IoC container (~350 lines) with constructor and property injection
• Type Safety -- Full TypeScript with Drizzle ORM type inference and Zod validation
• Auto-Generated API Docs -- OpenAPI/Swagger documentation out of the box via @hono/zod-openapi
• Decorator-Based Routing -- Clean, declarative route definitions with @get, @post, @controller
• Component System -- Pluggable modules for Auth (JWT/Basic), Health Checks, Swagger, Mail, Socket.IO, Static Assets
• Convention-Based Boot -- Auto-discovers controllers, services, repositories, datasources by file conventions
• Production Utilities -- Logger, Redis, BullMQ queues, MinIO storage, Crypto, Cron, Snowflake UID, and more
• Multi-Runtime -- Primary support for Bun, secondary support for Node.js

When Should You Use Ignis?

Perfect For

• E-commerce Backends -- Complex business logic, multiple controllers, auth, payments
• SaaS Platform APIs -- Multi-tenant architecture, modular components
• Enterprise Tools -- Team collaboration with clear architectural patterns
• Growing APIs -- 10+ endpoints that need structure and maintainability

Not Recommended For

• Simple Proxies/Webhooks -- Too much structure for tiny services
• Quick Prototypes -- Use plain Hono for maximum speed
• 3-5 Endpoint APIs -- Consider plain Hono unless you plan to grow

Framework Comparison

Feature Matrix

Same Endpoint in Ignis

@controller({ path: '/users' })
export class UserController extends BaseController {
  constructor(
    @inject({ key: 'repositories.UserRepository' }) private userRepo: UserRepository,
  ) {
    super({ scope: 'UserController', path: '/users' });
  }

  @get({
    configs: {
      path: '/:id',
      method: HTTP.Methods.GET,
      request: { params: z.object({ id: z.string() }) },
      responses: jsonResponse({
        description: 'Get user by ID',
        schema: z.object({ id: z.string(), name: z.string(), email: z.string() }),
      }),
    },
  })
  async findById(c: TRouteContext) {
    const { id } = c.req.valid('param');
    const user = await this.userRepo.findById({ id });
    return c.json(user, HTTP.ResultCodes.RS_2.Ok);
  }
}

[!TIP] See the Philosophy page for detailed Express vs NestJS vs Ignis code comparisons.

Monorepo Packages

Dependency Graph

                    +-------------------+
                    |   dev-configs     |   Shared ESLint / Prettier / TypeScript configs
                    +--------+----------+
                             |
                    +--------v----------+
                    |    inversion      |   IoC container, @inject, @injectable
                    +--------+----------+
                             |
                    +--------v----------+
                    |     helpers       |   Logger, Redis, Queue, Storage, Crypto, ...
                    +--------+----------+
                             |
                    +--------v----------+
                    |      boot         |   Convention-based auto-discovery & bootstrapping
                    +--------+----------+
                             |
                    +--------v----------+
                    |      core         |   Application, Controllers, Repositories, Components
                    +-------------------+

Each package builds on the previous. Changing inversion affects everything downstream.

Package Overview

[!TIP] Each package has its own detailed README with API reference, usage examples, and configuration options.

Prerequisites

Installation

1. Create a New Project

mkdir my-ignis-app
cd my-ignis-app
bun init -y

2. Install Dependencies

Production Dependencies:

bun add hono @hono/zod-openapi @scalar/hono-api-reference @venizia/ignis dotenv-flow
bun add drizzle-orm drizzle-zod pg lodash

Development Dependencies:

bun add -d typescript @types/bun @venizia/dev-configs
bun add -d tsc-alias
bun add -d drizzle-kit @types/pg @types/lodash

[!IMPORTANT] Both experimentalDecorators and emitDecoratorMetadata must be true in your tsconfig.json. The easiest way is to extend @venizia/dev-configs/tsconfig.common.json.

Quick Start -- Hello World

Minimal Example (Single File)

Create src/index.ts:

import { z } from '@hono/zod-openapi';
import {
  BaseApplication,
  BaseController,
  controller,
  get,
  HTTP,
  IApplicationInfo,
  jsonContent,
} from '@venizia/ignis';
import { Context } from 'hono';

// 1. Define a controller
@controller({ path: '/hello' })
class HelloController extends BaseController {
  constructor() {
    super({ scope: 'HelloController', path: '/hello' });
  }

  override binding() {}

  @get({
    configs: {
      path: '/',
      method: HTTP.Methods.GET,
      responses: {
        [HTTP.ResultCodes.RS_2.Ok]: jsonContent({
          description: 'Says hello',
          schema: z.object({ message: z.string() }),
        }),
      },
    },
  })
  sayHello(c: Context) {
    return c.json({ message: 'Hello from Ignis!' }, HTTP.ResultCodes.RS_2.Ok);
  }
}

// 2. Create the application
class App extends BaseApplication {
  getAppInfo(): IApplicationInfo {
    return { name: 'my-app', version: '1.0.0', description: 'My first Ignis app' };
  }

  staticConfigure() {}

  preConfigure() {
    this.controller(HelloController);
  }

  postConfigure() {}
  setupMiddlewares() {}
}

// 3. Start the server
const app = new App({
  scope: 'App',
  config: {
    host: '0.0.0.0',
    port: 3000,
    path: { base: '/api', isStrict: false },
  },
});

app.start();

Run the Application

bun run src/index.ts

Test the endpoint:

curl http://localhost:3000/api/hello
# Response: {"message":"Hello from Ignis!"}

View API Documentation:

Open http://localhost:3000/doc/explorer in your browser for interactive Swagger UI documentation.

[!TIP] See the complete CRUD tutorial and 5-minute quickstart example for a full working API with database, models, repositories, and auto-generated CRUD endpoints.

Architecture Flow

  HTTP Request
  GET /api/todos/:id
        |
        v
  +------------------+
  |  Hono Router      |  <-- OpenAPIHono with Zod schema validation
  +--------+---------+
           |
           v
  +------------------+
  |  Auth Middleware   |  <-- JWT/Basic token verification (optional per route)
  +--------+---------+
           |
           v
  +------------------+
  |  Controller       |  <-- Handles HTTP, validates input, OpenAPI specs
  |  @get('/...')     |
  +--------+---------+
           |
           v
  +------------------+
  |  Service          |  <-- Business logic (optional layer)
  |  (optional)       |
  +--------+---------+
           |
           v
  +------------------+
  |  Repository       |  <-- Type-safe data access (find, create, update, delete)
  |  findById(id)     |      Mixins: FieldsVisibility, DefaultFilter
  +--------+---------+
           |
           v
  +------------------+
  |  DataSource       |  <-- Drizzle ORM + node-postgres connection pool
  |  (singleton)      |      Schema auto-discovery from @repository bindings
  +--------+---------+
           |
           v
  +------------------+
  |   PostgreSQL      |
  +------------------+

Dependency Injection

@controller({ path: '/users' })
export class UserController extends BaseController {
  constructor(
    @inject({ key: 'services.UserService' }) private userService: UserService,
  ) {
    super({ scope: 'UserController', path: '/users' });
  }
}

Bindings are namespaced: "controllers.UserController", "services.AuthService", "repositories.UserRepo". The namespace automatically becomes a tag for discovery.

[!NOTE] See the Core Concepts documentation for DI flow details, boot sequence, request lifecycle, repository pattern, transaction support, and models with enrichers.

Application Lifecycle

Phases 3, 4, 5, and 9 are automatic -- you only need to implement the others.

Built-in Components

Register components in preConfigure():

class App extends BaseApplication {
  preConfigure() {
    this.component(HealthCheckComponent);
    this.component(SwaggerComponent);
    this.component(AuthenticateComponent);
  }
}

Component Catalog

[!TIP] See the Core README for detailed component configuration, authentication setup, and ControllerFactory auto-generated CRUD.

Helpers Ecosystem

The @venizia/ignis-helpers package provides production-ready infrastructure utilities. Each helper extends BaseHelper and follows the same pattern:

Full helpers documentation ->

Project Structure

my-ignis-app/
  src/
    application.ts            # Application configuration and lifecycle
    index.ts                  # Entry point
    migration.ts              # Drizzle migration configuration
    controllers/              # HTTP request handlers
    services/                 # Business logic
    repositories/             # Data access layer
    models/entities/          # Database models (Drizzle pgTable + BaseEntity)
    datasources/              # Database connections
    components/               # Reusable modules
  .env.development
  tsconfig.json

The boot system auto-discovers files by convention:

• controllers/*.controller.{ts,js} -> Registered as transient bindings
• services/*.service.{ts,js} -> Registered as transient bindings
• repositories/*.repository.{ts,js} -> Registered as transient bindings
• datasources/*.datasource.{ts,js} -> Registered as singleton bindings

Monorepo Development

Key Commands

# Build all packages (respects dependency order)
make build

# Build specific package (includes all dependencies)
make core        # Builds dev-configs -> inversion -> helpers -> boot -> core
make boot        # Builds dev-configs -> inversion -> helpers -> boot

# Clean all build artifacts
make clean

# Lint
make lint        # Lint all packages
make lint-all    # Lint packages and examples

# Test (from package directory)
cd packages/core && bun test

# Build individual package
cd packages/core && bun run rebuild

Examples

The examples/ directory contains reference implementations:

Running the Reference Example

cd examples/vert

# Copy environment template
cp .env.example .env.development

# Edit .env.development with your PostgreSQL credentials

# Install and run
bun install
bun run migrate:dev    # Push schema to database
bun run server:dev     # Start development server

Frequently Asked Questions

Can I use Ignis with Node.js instead of Bun?

Yes. Bun is the primary runtime and provides the best performance, but Ignis supports Node.js >= 18 as a secondary runtime. The framework detects the runtime automatically and uses @hono/node-server when running on Node.js instead of Bun.serve. Some helpers (like Bun-native WebSocket) are Bun-specific, but the core framework, controllers, repositories, and components all work on Node.js.

Can I use MySQL or SQLite instead of PostgreSQL?

Drizzle ORM supports MySQL and SQLite, but Ignis repositories are built around pgTable (PostgreSQL table definitions). The where operators, filter builders, and query generation assume PostgreSQL semantics. Using MySQL or SQLite would require building custom repository implementations.

How does Ignis compare to LoopBack 4?

Is Ignis production-ready?

Ignis is at version 0.x, which means the API may have breaking changes between minor versions. However, it is used internally in production at VENIZIA AI. The core patterns (controllers, repositories, DI, components) are stable. We recommend pinning exact versions and testing thoroughly before upgrading.

[!TIP] See the full documentation for more FAQs covering middleware, relations, route patterns, and deployment.

Documentation

Online Documentation: https://venizia-ai.github.io/ignis

The documentation covers getting started, core concepts (application lifecycle, controllers, DI, repositories, components), best practices (architecture, security, performance), API references, and deployment guides.

Key links: Philosophy • 5-Minute Quickstart • Building a CRUD API • Core Concepts • Best Practices

Contributing

Contributions are welcome! Please read our:

• Contributing Guide -- How to contribute
• Code of Conduct -- Community guidelines
• Security Policy -- Reporting vulnerabilities

Development Setup

# Clone the repository
git clone https://github.com/venizia-ai/ignis.git
cd ignis

# Install dependencies
bun install

# Build all packages
make build

# Run documentation locally
bun run docs:dev

Code Conventions

• Conventional Commits: feat:, fix:, docs:, chore:, refactor:, test:
• Branch naming: feature/*, fix/*, docs/*, chore/*
• PRs target develop -- never main directly
• Options objects: fn({ key, value }) not fn(key, value)
• Package manager: Bun only -- never npm, yarn, or pnpm
• Build tool: tsc directly -- never npx, bunx, or bun x

License

This project is licensed under the MIT License -- see the LICENSE.md file for details.

Acknowledgments

Ignis is inspired by:

• LoopBack 4 -- Enterprise patterns, decorator-based DI, repository pattern, component system
• Hono -- Performance, modern API design, multi-runtime support
• Drizzle ORM -- Type-safe SQL, schema-first approach
• NestJS -- Module system concepts, decorator patterns
• Spring Boot -- IoC/DI container design, auto-configuration patterns

Support

• Documentation: https://venizia-ai.github.io/ignis
• GitHub Issues: https://github.com/VENIZIA-AI/ignis/issues
• Author: VENIZIA AI Developer developer@venizia.ai