Nael Framework Docs

title: 'Getting Started · Nael Framework' description: 'Scaffold and run Nael Framework services with the CLI or the monorepo examples.'

Guide

Getting started

Install the CLI, scaffold a Bun-native service, and explore the curated examples. The CLI mirrors NestJS ergonomics while running entirely on Bun for faster startup times.

1. Install the CLI

The nl binary ships generators for new services, modules, controllers, resolvers, and background workers.

Install globally
bun install --global @nl-framework/cli
2. Scaffold a service

Choose HTTP, GraphQL, Better Auth, or microservice blueprints. The CLI always boots a NaelFactory instance wired with logging and configuration.

Create fleet-service
nl new fleet-servicecd fleet-servicebun installbun run dev

3. Run an example locally

Every capability in the README maps to an example inside examples/. Build once at the root, then point the --cwd flag to the folder you want to explore.

Multi-tenant HTTP example
bun installbun run buildbun run --cwd examples/auth-multi-tenant-http start

Multi-tenant Better Auth

The auth-multi-tenant-* examples demonstrate how to hydrate per-tenant configuration, reuse HTTP auth routes, and expose Better Auth via GraphQL. Key steps:

  • Register tenant metadata inside config/tenants.yaml and expose typed config tokens.

  • Use BetterAuthMultiTenantGuard to bind sessions to the active tenant.

  • Forward the Better Auth HTTP router via BetterAuthProxyModule so SPA clients stay in sync.

  • Re-use the exported guard in GraphQL resolvers via @UseGuards().

Need a federation-friendly flavor? Switch to examples/auth-multi-tenant-graphql and follow the README inside that folder.

What the CLI creates

  • NaelFactory bootstrap

    Unified HTTP + GraphQL + Gateway wiring with shared dependency injection context.

  • Config + Logger

    YAML-backed config module and structured logging with child logger support.

  • Ready-to-wire Better Auth

    Shared session middleware across HTTP and GraphQL plus helpers for proxying the Better Auth routes.

  • Generator commands

    nl g module users, nl g controller auth, nl g resolver profile mirror NestJS-style ergonomics.

Next steps

Head to the Installation guide for per-package instructions or open any folder under examples/ for focused walkthroughs.