📑 Table of Contents

• What is nestelia?
• Features
• Quick Start
• Ecosystem
• Examples
  • Guard
  • Interceptor
  • GraphQL Subscription
• Testing
• Documentation
• Claude Code Skill
• License

🎯 What is nestelia?

nestelia brings the developer experience of NestJS to the Elysia ecosystem. Write familiar decorator-based controllers, wire up services via dependency injection, and structure your app into modules — all while running on Bun's blazing-fast HTTP engine.

If you know NestJS, you already know nestelia.

import "reflect-metadata";
import { Controller, Get, Injectable, Module, createElysiaApplication } from "nestelia";

@Injectable()
class GreetingService {
  greet(name: string) {
    return `Hello, ${name}!`;
  }
}

@Controller("/")
class AppController {
  constructor(private readonly greeting: GreetingService) {}

  @Get("/hello/:name")
  hello(@Param("name") name: string) {
    return this.greeting.greet(name);
  }
}

@Module({
  controllers: [AppController],
  providers: [GreetingService],
})
class AppModule {}

const app = await createElysiaApplication(AppModule);
app.listen(3000, () => console.log("🦊 Listening on http://localhost:3000"));

✨ Features

🏗️ Decorators

@Controller, @Get, @Post, @Body, @Param, @Query, @Headers, and the full Express-style routing surface you expect.

💉 Dependency Injection

Constructor-based DI with singleton, transient, and request scopes. Circular dependency detection and auto-wiring out of the box.

📦 Modules

Encapsulate controllers, providers, and imports. Re-use logic across apps with clean boundaries and explicit exports.

⚡ Lifecycle Hooks

OnModuleInit, OnApplicationBootstrap, OnModuleDestroy, and BeforeApplicationShutdown for deterministic startup & teardown.

🛡️ Guards, Interceptors & Pipes

Composable request pipeline. Auth guards, logging interceptors, validation pipes — all via decorators.

🌐 Exception Handling

Built-in HTTP exceptions (BadRequestException, NotFoundException, etc.) and custom @Catch() filters.

📝 Swagger / OpenAPI

Automatic OpenAPI documentation generated from decorators. Zero config for basic specs, full control when you need it.

⏰ Task Scheduling

Cron jobs, intervals, and timeouts via @Cron(), @Interval(), @Timeout() decorators.

🚀 Microservices

Redis, RabbitMQ, and TCP transports with @MessagePattern and @EventPattern handlers.

🚀 Quick Start

# 1. Create a new project
bun init -y

# 2. Install dependencies
bun add nestelia elysia reflect-metadata

# 3. Enable decorators in tsconfig.json
#    "experimentalDecorators": true
#    "emitDecoratorMetadata": true

src/main.ts

import "reflect-metadata";
import { Controller, Get, Module, createElysiaApplication } from "nestelia";

@Controller()
class AppController {
  @Get()
  index() {
    return { message: "Hello from nestelia!" };
  }
}

@Module({
  controllers: [AppController],
})
class AppModule {}

const app = await createElysiaApplication(AppModule);
app.listen(3000);

console.log("🦊 Server running at http://localhost:3000");

bun run src/main.ts
# → 🦊 Server running at http://localhost:3000

📦 Ecosystem

All packages are published under the single nestelia package with subpath exports.

| Import | Description | |--------|-------------| | nestelia | Core framework — DI, decorators, modules, lifecycle | | nestelia/scheduler | Cron jobs, intervals, timeouts | | nestelia/microservices | Redis, RabbitMQ, TCP transports | | nestelia/apollo | Apollo GraphQL code-first | | nestelia/passport | Passport.js authentication integration | | nestelia/testing | Isolated test modules with provider overrides | | nestelia/cache | Response caching with @CacheKey(), @CacheTTL() | | nestelia/rabbitmq | Advanced RabbitMQ messaging patterns | | nestelia/graphql-pubsub | Redis-backed PubSub for GraphQL subscriptions |

📚 Examples

Guard

import { Injectable, CanActivate, ExecutionContext } from "nestelia";

@Injectable()
class AuthGuard implements CanActivate {
  canActivate(ctx: ExecutionContext) {
    const request = ctx.switchToHttp().getRequest();
    return request.headers.authorization === "Bearer secret";
  }
}

@Controller()
class AppController {
  @Get("/protected")
  @UseGuards(AuthGuard)
  protected() {
    return { secret: "🎉 You passed!" };
  }
}

Interceptor

import { Injectable, NestInterceptor, ExecutionContext, CallHandler } from "nestelia";
import { map } from "rxjs/operators";

@Injectable()
class TransformInterceptor implements NestInterceptor {
  intercept(_ctx: ExecutionContext, next: CallHandler) {
    return next.handle().pipe(map(data => ({ data, timestamp: Date.now() })));
  }
}

GraphQL Subscription

import { Resolver, Query, Subscription } from "@nestelia/apollo";
import { PubSub } from "@nestelia/graphql-pubsub";

@Resolver()
class NotificationResolver {
  constructor(private readonly pubsub: PubSub) {}

  @Query()
  notifications() {
    return [];
  }

  @Subscription(() => String, { topics: "NEW_NOTIFICATION" })
  newNotification() {
    return this.pubsub.asyncIterator("NEW_NOTIFICATION");
  }
}

🧪 Testing

import { Test } from "nestelia/testing";
import { AppController } from "./app.controller";
import { AppService } from "./app.service";

describe("AppController", () => {
  let controller: AppController;

  beforeAll(async () => {
    const module = await Test.createTestingModule({
      controllers: [AppController],
      providers: [AppService],
    }).compile();

    controller = module.get(AppController);
  });

  it("should return hello", () => {
    expect(controller.hello("World")).toEqual("Hello, World!");
  });
});

📖 Documentation

Full guides, API references, and recipes are available at nestelia.dev.

Run the docs locally:

bun install
bun run docs:dev

🤖 Claude Code Skill

A first-party Claude Code skill is available for nestelia. It provides scaffolding templates, decorator usage patterns, and framework best practices directly inside your AI assistant.

npx skills add nestelia/nestelia

⭐ Star History

📄 License

MIT © Islam Kiiasov