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

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 adapter (recommended):

bun add @asenajs/asena @asenajs/ergenecore @asenajs/asena-logger
bun add -D @asenajs/asena-cli

For Hono adapter:

bun add @asenajs/asena @asenajs/hono-adapter hono @asenajs/asena-logger
bun add -D @asenajs/asena-cli

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:

For Ergenecore:

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

const adapter = createErgenecoreAdapter();

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

await server.start();

For Hono:

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

For Ergenecore:

import { Controller } from '@asenajs/asena/server';
import { Get } from '@asenajs/asena/web';
import type { Context } from '@asenajs/ergenecore/types';

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

For Hono:

import { Controller } from '@asenajs/asena/server';
import { Get } from '@asenajs/asena/web';
import type { Context } from '@asenajs/hono-adapter/types';

@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:

asena dev start

Production build:

asena build
bun dist/index.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.