Get Started

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

Prerequisites

• Bun v1.2.8 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
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 hono @asenajs/asena-logger
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';

const adapter = createHonoAdapter();

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

await server.start();

6. Create Your First Controller

Create src/controllers/HelloController.ts:

Ergenecore

import { Controller } from '@asenajs/asena/server';
import { Get } from '@asenajs/asena/web';
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/server';
import { Get } from '@asenajs/asena/web';
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:

• Add more routes - Learn about Controllers
• Add business logic - Learn about Services
• Add middleware - Learn about Middleware
• Add validation - Learn about Validation (Ergenecore only)
• Explore CLI - Check out CLI Commands
• See examples - Browse Examples

---

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.