title: 'First Steps · Nael Framework' description: 'Learn how to create your first Nael Framework application with Bun runtime.'

Overview

First steps

In this guide, you'll learn the core fundamentals of Nael Framework. To get familiar with the essential building blocks of the framework, we'll build a basic HTTP application with features that cover a lot of ground at an introductory level.

Language

Nael Framework is built entirely for Bun, a fast all-in-one JavaScript runtime. We use TypeScript and leverage modern ES modules. While the framework is compatible with vanilla JavaScript, we strongly recommend using TypeScript for the best development experience.

Prerequisites

Please make sure that Bun (version >= 1.1.0) is installed on your operating system.

Setup

Setting up a new project is quite simple with the Nael CLI. With Bun installed, you can create a new project with the following commands:

Install CLI globally

bun install --global @nl-framework/cli

Create new project

nl new my-app

The my-app directory will be created, modules will be installed, and several boilerplate files will be created and populated. Here's a brief overview of the core files:

src/main.ts - The entry file of the application which uses the core function NaelFactory to create an application instance.
src/app.module.ts - The root module of the application.
src/app.controller.ts - A basic controller with a single route.
src/app.service.ts - A basic service with a single method.
config/default.yaml - Configuration file for different environments.

Main file

The main.ts includes an async function which will bootstrap our application:

src/main.ts

import { NaelFactory } from '@nl-framework/core';async function bootstrap() {  const app = await NaelFactory.create(AppModule);  await app.listen(3000);  console.log(`Application is running on: http://localhost:3000`);}bootstrap();

To create a Nael application instance, we use the core NaelFactory class. NaelFactory exposes a few static methods that allow creating an application instance. The create() method returns an application object, which implements the INaelApplication interface.

Application module

The application module (AppModule) is the root module of your application. Nael uses a module structure to organize components.

src/app.module.ts

import { Module } from '@nl-framework/core';@Module({  imports: [],  controllers: [AppController],  providers: [AppService],})export class AppModule {}

Controller

Controllers are responsible for handling incoming requests and returning responses to the client.

src/app.controller.ts

import { Controller, Get } from '@nl-framework/http';@Controller()export class AppController {  constructor(private readonly appService: AppService) {}  @Get()  getHello(): string {    return this.appService.getHello();  }}

The @Controller() decorator is required to define a basic controller. The @Get() HTTP request method decorator tells Nael to create a handler for a specific endpoint for HTTP requests.

Provider

Providers are a fundamental concept in Nael. Many of the basic classes may be treated as providers – services, repositories, factories, helpers, and so on.

src/app.service.ts

import { Injectable } from '@nl-framework/core';@Injectable()export class AppService {  getHello(): string {    return 'Hello Nael Framework!';  }}

The @Injectable() decorator attaches metadata, which declares that AppService is a class that can be managed by the Nael IoC container.

Running the application

Once the installation process is complete, you can run the following command to start the HTTP server:

Start development server

bun run dev

This command starts the app with the HTTP server listening on the port defined in config/default.yaml. Once the application is running, open your browser and navigate to http://localhost:3000/. You should see the Hello Nael Framework! message.

What's next?

Now that you have a basic understanding of how to create a Nael application, it's time to dive deeper into the framework's features. The next sections will cover Controllers, Providers, and Modules in more detail.