Igniter.js

Igniter.js is an AI-native TypeScript framework designed for seamless human-AI collaboration. It uses a low-entropy, predictable architecture (Feature-Sliced Architecture) to make codebases easily navigable for Code Agents like Cursor, Claude Code, GitHub Copilot, and Gemini CLI.

Key characteristics include:

• AI-First Design: Uses explicit patterns, composition over inheritance, and self-contained modules to reduce ambiguity for AI agents.
• End-to-End Type Safety: Provides pure TypeScript inference from server to client without manual type definitions or code generation.
• Framework Agnostic: Built on Web Standards (Request/Response), allowing the same business logic to run on Next.js, Express, Hono, Bun, or Deno.
• Production Ready: Includes built-in support for SSE/WebSockets, background jobs (BullMQ), caching (Redis), and observability (OpenTelemetry).

The initial release of Igniter.js introduces several foundational framework features:

• Type-Safe Router: A procedure-based routing system that supports middleware.
• Controller Actions: Type-safe actions for handling requests and responses within controllers.
• Procedure System: A middleware chain mechanism that provides execution control and context injection.
• Error Handling: Integrated error handling and response processing capabilities.

Igniter.js provides tailored installation and setup guides for several popular frameworks. You can choose the one that best fits your development environment:

• Next.js: Full-stack React framework with SSR and API routes.
• Vite: Lightning-fast build tool for modern web projects.
• Express: Fast, unopinionated web framework for Node.js.
• Bun: Fast all-in-one JavaScript runtime and toolkit.
• Deno: Secure runtime for JavaScript and TypeScript.

Igniter.js is a type-safe framework designed to bridge the gap between frontend and backend. Its core features include:

1. Type-Safe Controllers and Actions: Ensures end-to-end type safety for API interactions.
2. Procedures: Reusable type-safe middleware for handling logic across the stack.
3. Real-Time Updates by Default: Built-in support for real-time capabilities.
4. Background Jobs with Type Safety: Integrated job queues that maintain type integrity.
5. Framework-Agnostic Architecture: Designed to work across different environments and frameworks.

The Jobs system includes the following capabilities:

• Type-Safe Job Definitions: Uses Zod schemas for compile-time and runtime type safety.
• Background Processing: Offloads long-running tasks to prevent blocking APIs.
• Flexible Scheduling: Supports delayed execution and recurring cron jobs.
• Comprehensive Retry Logic: Includes exponential backoff, linear, and custom delay strategies.
• Job Lifecycle Hooks: Provides onStart, onSuccess, onFailure, and onComplete hooks.
• Multi-Tenancy Support: Uses namespaces and queue prefixes to organize jobs.
• Advanced Monitoring: Tools to search, filter, and monitor job status and execution times.

Middleware is a function that runs in the processing pipeline before your command handlers and event listeners. It is used to implement cross-cutting concerns such as authentication, logging, and rate limiting.

Middleware receives the BotContext and a next function. By calling await next(), you pass control to the next middleware in the chain or to the command handler. If you do not call next(), the request processing stops, effectively blocking the command from executing.

type Middleware = (
  ctx: BotContext,
  next: () => Promise<void>
) => Promise<void>

A Router acts as a controller for your background jobs, allowing you to group related jobs under a specific namespace. This provides a structured, namespaced API for invoking jobs and enables shared configuration (like queues or retry attempts) across all jobs within that group. Routers improve code organization and provide full TypeScript type safety for job names and inputs.

// Organized structure using routers
const emailRouter = jobs.router({
  namespace: 'emails',
  jobs: {
    sendWelcome: sendWelcomeJob,
    sendPasswordReset: sendPasswordResetJob,
  },
});

Context is the foundational object in an Igniter.js application. It acts as a container for shared data and dependencies that flow through every action, procedure, and middleware. It typically contains:

• Application Dependencies: Database connections, service instances (e.g., email, storage), and global configuration.
• Request-Specific Data: User authentication state, session information, request IDs, and telemetry metadata.

You initialize the Igniter instance by providing a context via the .context() method.

import { Igniter } from '@igniter-js/core';

export function createIgniterAppContext(): AppContext {
  return {
    db: new Database(),
    config: loadAppConfig(),
    services: {
      email: new EmailService(),
      storage: new StorageService()
    }
  };
}

const igniter = Igniter
  .context(createIgniterAppContext())
  .create();

When using an Igniter.js starter template with MCP enabled, your AI assistant gains a specialized persona called Lia.

Lia is an AI agent trained specifically for Igniter.js development. Unlike generic AI assistants that guess at project structure, Lia provides:

• Contextual Understanding: Analyzes project structure, conventions, and existing patterns before acting.
• Tool Prioritization: Automatically uses specialized Igniter.js tools (like generateController) instead of generic coding approaches.
• Pattern Replication: Learns from your existing code to maintain architectural consistency.
• Persistent Memory: Stores architectural decisions and patterns to improve future development speed.

In Igniter.js, a feature is a self-contained module that groups all logic related to a specific entity or business domain. A feature typically consists of:

• Controllers: Define HTTP endpoints (routes, methods, and handlers).
• Services: Encapsulate business logic and database access.
• Procedures: Middleware used for dependency injection (e.g., injecting services into the request context).
• Interfaces: Centralize types, Zod schemas, and constants.

Choosing between an alias and a new command depends on whether the behavior changes.

Use aliases when:

• The commands perform the exact same action.
• You want to provide convenience (e.g., /ls for /list).
• You want to support synonyms or different languages.

Create separate commands when:

• The commands have different behaviors or logic.
• The commands require different parameters.
• The commands need different help text.