Nael Framework Docs

title: 'Overview · Nael Framework' description: 'Learn about Nael Framework philosophy, installation options, Better Auth integration, GraphQL, and microservices support.'

Bun-native · Multi-tenant · OSS
Introduction

Nael Framework Overview

A NestJS-inspired framework that runs entirely on Bun. Combine Better Auth, Apollo Federation, Dapr microservices, and schedulers without juggling multiple ecosystems. This page mirrors nestjs.com depth so you can ship production-ready services quickly.

What you get

Decorator-driven modules, Bun-native HTTP and GraphQL servers, shared DI contexts, and full Better Auth integration (single-tenant and multi-tenant) with zero CommonJS shims.

Release cadence

Weekly alpha releases keep the framework aligned with Bun updates and Better Auth changes. Subscribe to the changelog in the right rail or star the repo to follow along.

Philosophy

Inspired by NestJS but optimized for Bun, Nael keeps the “lego-brick” approach to modules while shedding layered build steps. Everything is native ESM, meaning faster cold starts, effortless workers, and aligned tooling.

  • Decorators + DI you already know from NestJS.
  • Unified HTTP, GraphQL, federation gateway, and microservices factories via NaelFactory.
  • Better Auth-first mindset: guards, middleware, tenant-aware resolvers, and HTTP proxies included.
  • CLI automation with nl new and nl g * commands.
Installation

Start from the CLI or clone the repo

Choose the workflow that matches your team. The CLI scaffolds clean services, while the monorepo unlocks every example and package.

CLI workflow

Create a service
bun install --global @nl-framework/clinl new platform-democd platform-demobun run dev

Generates HTTP + GraphQL boilerplate, registers Better Auth, and wires config/logging. Run nl g module billing or nl g resolver user as you grow the surface area.

Monorepo workflow

Clone the repository
git clone https://github.com/Nael-Studio/nael-platform.gitcd nael-platformbun installbun run build

Ideal for contributing or exploring every package. Each example has its own start script and shares dependencies via Bun workspaces.

Alternatives

Prefer to skip commit history?

Shallow clone and explore
git clone https://github.com/Nael-Studio/nael-platform.git --depth=1 --single-branchcd nael-platformbun run --cwd examples/basic-http start

Great for CI examples or one-off demos. Run dapr init and start the microservices example without keeping git history around.

Techniques

Better Auth everywhere

Shared guards, middleware, and HTTP proxies mean REST + GraphQL stay in sync. Enable tenant-aware sessions with a single config block.

Register BetterAuthModule
import { BetterAuthModule } from '@nl-framework/auth';@Module({  imports: [    BetterAuthModule.register({      baseUrl: env.BETTER_AUTH_URL,      multiTenant: true,    }),  ],})export class AuthModule {}
  • Expose the Better Auth HTTP router via BetterAuthProxyModule for SPA compatibility.
  • Use BetterAuthMultiTenantGuard to hydrate the active tenant.
  • Reuse guards inside GraphQL resolvers with @UseGuards().

GraphQL & Federation

Schema-first development with Apollo Server under the hood. Run a gateway and subgraphs from the same NaelFactory instance or deploy them independently.

GraphqlModule setup
GraphqlModule.forRoot({  schemaPath: './src/schema.graphql',  federation: true,  playground: true,});

Each resolver module can opt-in to federation without toggling feature flags. Subgraphs share the logging + config stack automatically.

  • Decorators such as @UseInterceptors() now wrap GraphQL resolvers, allowing shared caching/logging envelopes across transports.
  • Register global resolver middleware with registerGraphqlInterceptor() to apply observability or auth layers everywhere.

Microservices & schedulers

Dapr pub/sub transports, Bun Worker schedulers, and message pattern decorators mirror the NestJS API you already know.

createMicroservicesModule
createMicroservicesModule({  controllers: [BillingController],  dapr: {    pubsubName: 'redis-pubsub',  },});
  • Decorators: @MessagePattern, @EventPattern, @Cron, @Interval, @Timeout.
  • CLI command nl g worker invoices scaffolds workers tied to the scheduler module.
  • Examples cover Redis pub/sub, Dapr sidecars, and Kubernetes deployment manifests.
Examples

Hands-on references

Browse repo

Hands-on references

Examples directory

Every capability in the README ships with a runnable sample. Switch the folder name to explore a different scenario.

auth-multi-tenant-graphql

Combines Better Auth, tenant guards, and GraphQL resolvers with shared session middleware.

bun run --cwd examples/auth-multi-tenant-graphql start

federated-graphql

Schema-first Apollo Federation subgraph with resolver discovery and NaelFactory wiring.

bun run --cwd examples/federated-graphql start

microservices

Dapr-based pub/sub microservice with message patterns, cron workers, and deployment notes.

bun run --cwd examples/microservices dapr

scheduler

Bun Worker-powered cron, interval, and timeout decorators with runtime registry APIs.

bun run --cwd examples/scheduler start
Support

Support us

Nael is MIT + Apache 2.0 and depends on sponsors. If the framework powers your platform, consider funding maintenance and roadmap items.

Principal sponsors

Trilon, Mach10, and the Nael Studio collective keep CI running and ensure Better Auth parity. Your company can join them.

Partners
We highlight ecosystem partners building on Nael (hosting, observability, dashboards).

Become a sponsor