Get Started

Get up and running with Asena in minutes. This guide shows you how to create your first Asena application.

Prerequisites

• Bun v1.4 or higher

Verify Bun installation:

bun --version

Option 1: With Asena CLI (Recommended)

The fastest way to create a new Asena project.

1. Install Asena CLI

bun install -g @asenajs/asena-cli

2. Create Project

asena create

Answer the interactive prompts:

✔ Enter your project name: my-app
✔ Select adapter: Ergenecore
✔ Do you want to setup ESLint? No
✔ Do you want to setup Prettier? No

3. Start Development Server

cd my-app
asena dev start

WARNING

You shouldn't use asena dev start for production. It will be removed in feature releases. Its for quick testings only

Your server is now running at http://localhost:3000!

Test it:

curl http://localhost:3000
# Output: Hello asena

That's it! You now have a working Asena application. Skip to Next Steps to learn more.

---

Option 2: Manual Setup

If you prefer to set up your project manually.

1. Create Project

mkdir my-app
cd my-app
bun init -y

2. Install Dependencies

For ergenecore

bun add @asenajs/asena @asenajs/ergenecore @asenajs/asena-logger zod
bun add -D @asenajs/asena-cli
bunx asena init
✔ Which adapter do you want to use? Ergenecore Adapter

For hono

bun add @asenajs/asena @asenajs/hono-adapter @asenajs/asena-logger hono zod
bun add -D @asenajs/asena-cli
bunx asena init
✔ Which adapter do you want to use? Hono Adapter

3. Configure TypeScript

Update your tsconfig.json to enable decorators:

{
  "compilerOptions": {
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true
  }
}

TIP

These two settings are required for Asena decorators to work properly.

4. Create Logger

Create src/logger.ts:

import { AsenaLogger } from '@asenajs/asena-logger';

export const logger = new AsenaLogger();

5. Create Entry Point

Create src/index.ts:

Ergenecore

import { AsenaServerFactory } from '@asenajs/asena';
import { createErgenecoreAdapter } from '@asenajs/ergenecore';
import { logger } from './logger';

const adapter = createErgenecoreAdapter();

const server = await AsenaServerFactory.create({
  adapter,
  logger,
  port: 3000
});

await server.start();

Hono

import { AsenaServerFactory } from '@asenajs/asena';
import { createHonoAdapter } from '@asenajs/hono-adapter';
import { logger } from './logger';

// createHonoAdapter returns a tuple and requires a logger
const [adapter] = createHonoAdapter({ logger });

const server = await AsenaServerFactory.create({
  adapter,
  logger,
  port: 3000
});

await server.start();

Components in the entry file

Asena never forces you to split everything into separate files - a small app can declare a @Controller or @Service directly in src/index.ts and it will be registered as usual.

Declare it above the AsenaServerFactory.create() call. Anything below that line has not been evaluated yet when components are collected, so it cannot be registered; Asena logs a warning naming any component it finds in that position.

6. Create Your First Controller

Create src/controllers/HelloController.ts:

Ergenecore

import { Controller } from '@asenajs/asena/decorators';
import { Get } from '@asenajs/asena/decorators/http';
import { type Context } from '@asenajs/ergenecore';

@Controller('/')
export class HelloController {
  @Get('/')
  async hello(context: Context) {
    return context.send('Hello World!');
  }
}

Hono

import { Controller } from '@asenajs/asena/decorators';
import { Get } from '@asenajs/asena/decorators/http';
import { type Context } from '@asenajs/hono-adapter';

@Controller('/')
export class HelloController {
  @Get('/')
  async hello(context: Context) {
    return context.send('Hello World!');
  }
}

7. Initialize CLI Configuration

asena init

This creates asena-config.ts with default build settings.

8. Run Your Application

Development mode:

# index.ts must be your root file
bun run src/index.ts

Hot Reload for Faster Development

Enable hot reloading to automatically restart your server on file changes:

bun run --hot src/index.ts

What hot reload does:

• Watches all source files for changes
• Automatically refreshes the server process
• Preserves in-memory state when possible
• Ideal for rapid iteration and testing

Production build:

asena build
bun dist/index.asena.js

Test your application:

curl http://localhost:3000
# Output: Hello World!

---

Project Structure

Your project should now look like this:

my-app/
├── src/
│   ├── controllers/
│   │   └── HelloController.ts
│   ├── index.ts
│   └── logger.ts
├── asena-config.ts
├── package.json
└── tsconfig.json

---

Next Steps

Now that you have a working Asena application:

Routing

Controllers

Add more routes to your application.

Business Logic

Services

Injectable components that carry your logic.

Requests

Middleware

Intercept requests at any level.

Type Safety

Validation

Zod-based request validation on routes.

Background Jobs

Scheduled Tasks

Cron-based task scheduling.

HTML Pages

Frontend Controller

Serve HTML pages with native imports.

API Docs

OpenAPI

Auto-generate OpenAPI 3.1 specs.

Caching

Redis

Caching and multi-pod WebSocket transport.

Tooling

CLI Commands

Scaffold, generate and build from the terminal.

Reference

Examples

Browse ready-to-run example projects.

---

Common Issues

Decorators not working

Make sure your tsconfig.json has:

{
  "compilerOptions": {
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true
  }
}

Command not found: asena

Add Bun's global bin directory to your PATH:

# For bash
echo 'export PATH="$HOME/.bun/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

# For zsh
echo 'export PATH="$HOME/.bun/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Port already in use

Change the port in AsenaServerFactory.create():

const server = await AsenaServerFactory.create({
  adapter,
  logger,
  port: 3001
});

---

Need help? Check out our documentation or visit our GitHub repository.