Bueno

A Bun-Native Full-Stack Framework

Why Bueno?

Bueno is a Bun-native full-stack framework designed from the ground up to leverage Bun's exceptional performance and modern JavaScript capabilities. Bueno embraces Bun's APIs, resulting in:

• Blazing Fast Performance: Built on Bun's native HTTP server and optimized runtime
• Zero Dependencies: True zero-dependency framework with built-in validation, ORM, caching, and jobs
• Zero Configuration: Sensible defaults that work out of the box
• Full-Stack Integration: Seamless frontend and backend development
• Type Safety: End-to-end TypeScript with full type inference
• Modern DX: Hot module replacement, fast testing, and intuitive APIs

Installation

Quick Start (New Project)

# Create a new project (recommended)
bunx create-bueno my-app
cd my-app
bun install
bun dev

Add to Existing Project

# As a dependency
bun add @buenojs/bueno

Global CLI Installation

# Install globally
bun install -g @buenojs/bueno

# Use CLI commands anywhere
bueno dev
bueno build

Quick Start

import { createServer, Router } from '@buenojs/bueno';

const router = new Router();

router.get('/hello', (ctx) => {
  return ctx.json({ message: 'Hello, World!' });
});

const server = createServer();
server.router = router;
server.listen(3000);

CLI Commands

bueno new <name>

Create a new Bueno project with automatic frontend setup for fullstack template.

bueno new my-app
bueno new my-api --template api
bueno new my-fullstack --template fullstack --framework react
bueno new my-app --database postgresql --docker

Two-Stage Fullstack Creation: When using --template fullstack, Bueno creates your project in two stages:

1. Stage 1: Creates the API backend with your chosen database
2. Stage 2: Automatically runs add:frontend with your selected framework

# Creates API + React frontend together
bueno new my-app --template fullstack --framework react

# Creates API + Vue frontend together
bueno new my-app --template fullstack --framework vue --database postgresql

| Option | Default | Description | |--------|---------|-------------| | --template | default | Project template (default, minimal, fullstack, api, website) | | --framework | react | Frontend framework (react, vue, svelte, solid) | | --database | sqlite | Database type (sqlite, postgresql, mysql) | | --docker | false | Generate Docker configuration | | --deploy | - | Deployment target (render, fly, railway) | | --skip-install | false | Skip dependency installation | | --skip-git | false | Skip git initialization | | --yes | false | Use default options |

bueno add:frontend <framework>

Add a frontend framework to an existing Bueno project.

# Interactive prompt to choose framework
bueno add:frontend

# Add React frontend
bueno add:frontend react

# Add Vue frontend
bueno add:frontend vue

# Add Svelte frontend
bueno add:frontend svelte

# Add SolidJS frontend
bueno add:frontend solid

# Skip dependency installation
bueno add:frontend react --skip-install

What Gets Added:

• client/ directory with full frontend setup
• Framework-specific entry point (main.tsx or main.ts)
• Example components and styles
• Tailwind CSS + PostCSS configuration
• Bun bundler configuration (framework-optimized)
• TypeScript configuration for client
• Development scripts: dev:server, dev:client, dev (concurrent)
• Build script: build:client

Supported Frameworks: | Framework | Entry Point | JSX Mode | |-----------|-------------|----------| | React | client/src/main.tsx | react-jsx | | Vue | client/src/main.ts | N/A | | Svelte | client/src/main.ts | N/A | | SolidJS | client/src/main.tsx | preserve |

| Option | Default | Description | |--------|---------|-------------| | framework (positional) | (interactive) | Frontend framework (react, vue, svelte, solid) | | -f, --framework | - | Frontend framework as option | | --skip-install | false | Skip dependency installation |

bueno dev

Start the development server with Hot Module Replacement (HMR).

bueno dev
bueno dev --port 4000 --host 0.0.0.0
bueno dev --no-hmr --open

| Option | Default | Description | |--------|---------|-------------| | -p, --port | 3000 | Server port | | -H, --host | localhost | Server host | | --no-hmr | false | Disable Hot Module Replacement | | --no-watch | false | Disable file watching | | -o, --open | false | Open browser automatically | | -c, --config | bueno.config.ts | Configuration file path |

bueno build

Build your application for production.

bueno build
bueno build --target node --outdir ./dist
bueno build --compile --cross-compile

| Option | Default | Description | |--------|---------|-------------| | -t, --target | bun | Build target (bun, node, standalone) | | -o, --outdir | ./dist | Output directory | | --no-minify | false | Disable minification | | --sourcemap | false | Generate source maps | | --analyze | false | Analyze bundle size | | --compile | false | Compile to executable | | --cross-compile | false | Cross-compile for other platforms | | --executable-name | app | Executable name |

bueno start

Start the production server.

bueno start
bueno start --port 8080 --workers 4

| Option | Default | Description | |--------|---------|-------------| | -p, --port | 3000 | Server port | | -H, --host | 0.0.0.0 | Server host | | -w, --workers | 1 | Number of worker threads | | -c, --config | bueno.config.ts | Configuration file path |

bueno generate <type> <name>

Generate code artifacts (alias: g).

bueno generate controller UserController
bueno g service AuthService --module auth
bueno g dto CreateUserDTO --dry-run

| Type | Description | |------|-------------| | controller | HTTP controller | | service | Injectable service | | module | Feature module | | guard | Authentication/authorization guard | | interceptor | Request/response interceptor | | pipe | Validation/transformation pipe | | filter | Exception filter | | dto | Data Transfer Object | | middleware | Custom middleware | | migration | Database migration |

| Option | Default | Description | |--------|---------|-------------| | -m, --module | - | Parent module for the artifact | | --path | - | Custom output path | | --dry-run | false | Preview without writing | | --force | false | Overwrite existing files |

bueno migration <action>

Manage database migrations.

bueno migration create add_users_table
bueno migration up
bueno migration down --steps 2
bueno migration reset
bueno migration status

| Action | Description | |--------|-------------| | create <name> | Create a new migration | | up | Run pending migrations | | down | Rollback migrations | | reset | Reset database and re-run all migrations | | refresh | Reset and re-seed database | | status | Show migration status |

| Option | Default | Description | |--------|---------|-------------| | -n, --steps | 1 | Number of migrations to rollback | | --dry-run | false | Preview without executing |

bueno help

Display help information.

bueno help
bueno help dev
bueno generate --help

Global Options

| Option | Description | |--------|-------------| | --help, -h | Show help | | --version, -v | Show version | | --verbose | Enable verbose output | | --quiet | Suppress output | | --no-color | Disable colored output |

Core Features

Background Jobs

Job queue system with Redis and memory drivers.

import { JobQueue, createJobQueue, startWorker } from '@buenojs/bueno/jobs';

// Create a job queue
const queue = createJobQueue({
  driver: 'redis',
  redisUrl: 'redis://localhost:6379',
});

// Define a job handler
queue.registerHandler('send-email', async (job) => {
  const { to, subject, body } = job.data;
  await emailService.send(to, subject, body);
  return { success: true };
});

// Start a worker
startWorker(queue, { concurrency: 5 });

// Add a job to the queue
await queue.add('send-email', {
  to: '[email protected]',
  subject: 'Welcome!',
  body: 'Thank you for joining our platform.',
});

Notifications

Multi-channel notification system with support for email, SMS, WhatsApp, and push notifications.

import { NotificationService, createNotificationService, EmailChannelService } from '@buenojs/bueno/notification';

// Create notification service
const notificationService = createNotificationService({
  channels: [
    new EmailChannelService({
      smtp: {
        host: 'smtp.gmail.com',
        port: 587,
        auth: {
          user: '[email protected]',
          pass: 'your-password',
        },
      },
    }),
  ],
});

// Send a notification
await notificationService.send({
  to: '[email protected]',
  subject: 'Welcome!',
  body: 'Thank you for joining our platform.',
  channel: 'email',
});

Observability

Structured error tracking and observability integration.

import { createApp } from '@buenojs/bueno';
import { ObservabilityModule } from '@buenojs/bueno/observability';

const app = createApp(AppModule);

// Wire observability with custom reporter (e.g., Sentry)
const obs = ObservabilityModule.setup(app, {
  reporter: new MyReporter(),
  breadcrumbsSize: 20,
  ignoreStatusCodes: [404, 401],
  tags: { environment: 'production' },
});

await app.listen(3000);

Metrics

Runtime metrics collection for memory, CPU, and event loop lag.

import { MetricsCollector, createMetricsCollector, toPrometheusFormat } from '@buenojs/bueno/metrics';

// Create metrics collector
const collector = createMetricsCollector({
  maxHistorySize: 100,
  measureEventLoopLag: true,
});

// Collect metrics periodically
collector.startPeriodicCollection(5000);

// Get metrics
const metrics = collector.getLatest();
console.log(toPrometheusFormat(metrics));

i18n

Internationalization support with translation loading and locale negotiation.

import { I18n, createI18n, i18nMiddleware } from '@buenojs/bueno/i18n';

// Create i18n instance
const i18n = createI18n({
  defaultLocale: 'en',
  locales: ['en', 'fr', 'es'],
  translations: {
    en: {
      welcome: 'Welcome!',
      goodbye: 'Goodbye!',
    },
    fr: {
      welcome: 'Bienvenue!',
      goodbye: 'Au revoir!',
    },
  },
});

// Use middleware
server.use(i18nMiddleware(i18n));

HTTP & Routing

Bueno provides a powerful and intuitive routing system with full HTTP method support.

import { createServer, Router } from '@buenojs/bueno';

const router = new Router();

// All HTTP methods
router.get('/users', getUsers);
router.post('/users', createUser);
router.put('/users/:id', updateUser);
router.patch('/users/:id', patchUser);
router.delete('/users/:id', deleteUser);

// Path parameters
router.get('/users/:id', (ctx) => {
  const { id } = ctx.params;
  return ctx.json({ userId: id });
});

// Query parameters
router.get('/search', (ctx) => {
  const { q, page, limit } = ctx.query;
  return ctx.json({ query: q, page, limit });
});

// Wildcard routes
router.get('/files/*', (ctx) => {
  const path = ctx.params['*'];
  return ctx.json({ filePath: path });
});

// Route groups
router.group('/api/v1', (api) => {
  api.get('/users', getUsers);
  api.post('/users', createUser);
});

const server = createServer();
server.router = router;
server.listen(3000);

Dependency Injection

Built-in IoC container inspired by NestJS for clean, testable code.

import { Container, createToken, Injectable, Inject } from '@buenojs/bueno';

// Create tokens
const ILogger = createToken<Logger>('Logger');
const IUserRepository = createToken<UserRepository>('UserRepository');

// Define injectable services
@Injectable()
class UserRepository {
  constructor(@Inject(ILogger) private logger: Logger) {}
  
  async findById(id: string) {
    this.logger.debug(`Finding user ${id}`);
    // ...
  }
}

// Register and resolve
const container = new Container();
container.register(ILogger, ConsoleLogger);
container.register(IUserRepository, UserRepository);

const repo = container.resolve(IUserRepository);

Middleware

Comprehensive middleware system with built-in utilities and custom middleware support.

Built-in Middleware

import { 
  logger, 
  cors, 
  requestId, 
  timing, 
  securityHeaders, 
  rateLimit, 
  compression 
} from '@buenojs/bueno/middleware';

const server = createServer();

// Add middleware
server.use(logger());
server.use(cors({ origin: ['https://example.com'] }));
server.use(requestId());
server.use(timing());
server.use(securityHeaders());
server.use(rateLimit({ windowMs: 60000, max: 100 }));
server.use(compression());

Custom Middleware

import { compose, createPipeline } from '@buenojs/bueno/middleware';

// Compose multiple middleware
const apiMiddleware = compose([
  authMiddleware,
  rateLimitMiddleware,
  loggingMiddleware
]);

// Create custom pipeline
const pipeline = createPipeline()
  .use(authMiddleware)
  .use(validationMiddleware)
  .use(handler);

server.use('/api', apiMiddleware);

Modules System

NestJS-inspired modular architecture with decorators.

import { Module, Controller, Injectable, Get, Post, Body } from '@buenojs/bueno/modules';

@Injectable()
class UserService {
  private users: User[] = [];
  
  findAll() {
    return this.users;
  }
  
  create(data: CreateUserDTO) {
    const user = { id: crypto.randomUUID(), ...data };
    this.users.push(user);
    return user;
  }
}

@Controller('/users')
class UserController {
  constructor(private userService: UserService) {}
  
  @Get()
  findAll() {
    return this.userService.findAll();
  }
  
  @Post()
  create(@Body() data: CreateUserDTO) {
    return this.userService.create(data);
  }
}

@Module({
  controllers: [UserController],
  providers: [UserService],
})
class UserModule {}

Database

Multi-database support with migrations and schema builder.

import { Database, createConnection, SchemaBuilder } from '@buenojs/bueno/database';

// Create connection
const db = createConnection({
  type: 'postgresql', // 'sqlite' | 'mysql' | 'postgresql'
  host: 'localhost',
  port: 5432,
  database: 'myapp',
  username: 'user',
  password: 'pass',
});

// Query builder
const users = await db.table('users')
  .where('active', true)
  .orderBy('created_at', 'desc')
  .limit(10)
  .get();

// Schema builder
const schema = new SchemaBuilder(db);
await schema.createTable('users', (table) => {
  table.uuid('id').primary();
  table.string('email').unique().notNullable();
  table.string('name').notNullable();
  table.timestamp('created_at').default('now()');
  table.index(['email', 'name']);
});

Validation

Bueno includes a zero-dependency built-in validation system for common use cases, with optional support for external libraries like Zod, Valibot, and ArkType via the Standard Schema adapter.

Built-in Validation (No Dependencies)

import { Schema, Fields, validate, validateBody } from '@buenojs/bueno/validation';

// Define schema with built-in validators
const UserSchema = Schema.object({
  name: Fields.string({ min: 1, max: 100 }),
  email: Fields.string({ email: true }),
  age: Fields.number({ positive: true, optional: true }),
  role: Fields.enum(['admin', 'user', 'guest']),
});

// Validate in route
router.post('/users', async (ctx) => {
  const result = await validateBody(ctx, UserSchema);

  if (!result.success) {
    return ctx.status(400).json({
      error: 'Validation failed',
      issues: result.issues
    });
  }

  const user = result.data; // Fully typed!
});

Built-in Field Validators

import { Fields } from '@buenojs/bueno/validation';

Fields.string({
  min: 1,           // Minimum length
  max: 255,         // Maximum length
  pattern: /regex/, // Regex validation
  email: true,      // Email format
  url: true,        // URL format
  uuid: true,       // UUID format
  optional: true,   // Allow undefined/null
})

Fields.number({
  min: 0,           // Minimum value
  max: 100,         // Maximum value
  integer: true,    // Must be integer
  positive: true,   // Must be > 0
  optional: true,   // Allow undefined/null
})

Fields.boolean({ optional: true })

Fields.array({
  min: 1,           // Minimum items
  max: 10,          // Maximum items
  itemValidator: Fields.string(), // Validate each item
  optional: true,
})

Fields.enum(['admin', 'user'], { optional: true })

Fields.custom(
  (value) => typeof value === 'string' && value.length > 0,
  'Custom validation message'
)

Middleware Validation

import { createValidator } from '@buenojs/bueno/validation';

const validateUserInput = createValidator({
  body: UserSchema,
  query: QuerySchema,
  params: ParamsSchema,
  headers: HeadersSchema,
});

router.post('/users/:id', validateUserInput, async (ctx) => {
  const user = ctx.get('validatedBody');
  const params = ctx.get('validatedParams');
  // All validated and typed!
});

Optional: Use External Validators (Zod, Valibot, ArkType)

Bueno supports any Standard Schema-compatible library. Install your preferred validator and use it with Bueno's validation functions:

# Install your chosen validator (optional)
bun add zod
# or
bun add valibot
# or
bun add arktype

import { validate, validateBody } from '@buenojs/bueno/validation';
import { z } from 'zod'; // Optional, use any Standard Schema library

// Use Zod schema (or Valibot, ArkType, Typia)
const UserSchema = z.object({
  name: z.string().min(2),
  email: z.string().email(),
  age: z.number().int().positive().optional(),
});

// Works seamlessly with Bueno validators
router.post('/users', async (ctx) => {
  const result = await validateBody(ctx, UserSchema);

  if (!result.success) {
    return ctx.status(400).json({
      error: 'Validation failed',
      issues: result.issues
    });
  }

  const user = result.data;
});

Supported External Libraries

| Library | Minimum Version | Status | |---------|-----------------|--------| | Zod | 4.0+ | ✅ Supported | | Valibot | 1.0+ | ✅ Supported | | ArkType | 2.0+ | ✅ Supported | | Typia | 7.0+ | ✅ Supported |

All libraries using the Standard Schema interface are supported automatically.

Security

Comprehensive security features out of the box.

import { 
  hashPassword, 
  verifyPassword,
  createJWT,
  verifyJWT,
  csrf,
  auth,
  rbac,
  apiKey
} from '@buenojs/bueno/security';

// Password hashing
const hashedPassword = await hashPassword('user-password');
const isValid = await verifyPassword(hashedPassword, 'user-password');

// JWT
const token = createJWT({ userId: '123' }, { expiresIn: '1h' });
const payload = verifyJWT(token);

// CSRF protection
server.use(csrf());

// Auth middleware
server.use(auth({ 
  strategy: 'jwt',
  secret: process.env.JWT_SECRET 
}));

// RBAC
server.use(rbac({
  roles: ['admin', 'user', 'guest'],
  permissions: {
    admin: ['*'],
    user: ['read', 'write'],
    guest: ['read']
  }
}));

// API Key middleware
server.use('/api', apiKey({
  header: 'X-API-Key',
  validate: async (key) => await findApiKey(key)
}));

RPC Client

Type-safe API client generation for seamless frontend-backend communication.

// server/routes.ts
import { defineRoutes } from '@buenojs/bueno/rpc';

export const routes = defineRoutes((r) => ({
  getUsers: r.get('/users').response<User[]>(),
  getUser: r.get('/users/:id').response<User>(),
  createUser: r.post('/users').body<CreateUserDTO>().response<User>(),
}));

// client/api.ts
import { createClient } from '@buenojs/bueno/rpc';
import { routes } from '../shared/routes';

const api = createClient('http://localhost:3000', routes);

// Fully typed!
const users = await api.getUsers();
const user = await api.getUser({ id: '123' });
const newUser = await api.createUser({ name: 'John', email: '[email protected]' });

Caching & Sessions

Redis-backed caching and session management.

import { Cache, SessionStore, createRedisClient } from '@buenojs/bueno/cache';

// Redis cache
const redis = createRedisClient({ url: 'redis://localhost:6379' });
const cache = new Cache(redis);

await cache.set('user:123', userData, { ttl: 3600 });
const user = await cache.get<User>('user:123');

// Session store
const sessions = new SessionStore(redis);
const session = await sessions.create({ userId: '123' });
const data = await sessions.get(session.id);
await sessions.destroy(session.id);

Distributed Locking

Coordinate distributed operations with Redis or in-memory locks.

import { RedisLock, MemoryLock } from '@buenojs/bueno/lock';

// Redis-based distributed lock
const lock = new RedisLock(redis);
await lock.acquire('resource:123', { ttl: 5000 });
try {
  // Critical section
  await processResource();
} finally {
  await lock.release('resource:123');
}

// In-memory lock for single-instance apps
const memoryLock = new MemoryLock();

Static Site Generation (SSG)

Generate static sites with markdown support.

import { SSG, markdownParser } from '@buenojs/bueno/ssg';

const ssg = new SSG({
  contentDir: './content',
  outputDir: './dist',
  templates: './templates',
});

// Parse markdown
ssg.parser.use(markdownParser());

// Generate static pages
await ssg.build();

Storage

S3-compatible storage and secrets management.

import { Storage, SecretsManager } from '@buenojs/bueno/storage';

// S3-compatible storage
const storage = new Storage({
  provider: 's3',
  bucket: 'my-bucket',
  region: 'us-east-1',
  credentials: {
    accessKeyId: process.env.AWS_ACCESS_KEY,
    secretAccessKey: process.env.AWS_SECRET_KEY,
  },
});

await storage.upload('uploads/file.pdf', fileBuffer);
const file = await storage.download('uploads/file.pdf');

// Secrets management
const secrets = new SecretsManager({
  provider: 'aws-secrets-manager',
  secretId: 'my-app/secrets',
});

const dbPassword = await secrets.get('DATABASE_PASSWORD');

WebSocket

Real-time communication with WebSocket support.

import { WebSocketServer, WebSocketClient, PubSub } from '@buenojs/bueno/websocket';

// Server
const wss = new WebSocketServer({ port: 3001 });

wss.on('connection', (client) => {
  console.log('Client connected');
  
  client.on('message', (data) => {
    // Broadcast to all clients
    wss.broadcast({ type: 'chat', data });
  });
});

// PubSub
const pubsub = new PubSub(redis);
pubsub.subscribe('channel:updates', (message) => {
  wss.broadcast(message);
});

// Client
const ws = new WebSocketClient('ws://localhost:3001');
ws.on('message', (data) => console.log(data));
ws.send({ type: 'chat', message: 'Hello!' });

Logging

Flexible logging with multiple transports.

import { Logger, ConsoleTransport, FileTransport } from '@buenojs/bueno/logger';

const logger = new Logger({
  level: 'debug',
  transports: [
    new ConsoleTransport({ colorize: true }),
    new FileTransport({ path: './logs/app.log' }),
  ],
});

logger.info('Server started');
logger.error('Database connection failed', { error: err });
logger.debug('Request received', { method, path });

Health Checks

Built-in health check endpoints for monitoring.

import { HealthChecker, DatabaseCheck, CacheCheck, TCPCheck, HTTPCheck } from '@buenojs/bueno/health';

const health = new HealthChecker();

health.addCheck('database', new DatabaseCheck(db));
health.addCheck('redis', new CacheCheck(redis));
health.addCheck('api', new HTTPCheck('https://api.example.com/health'));
health.addCheck('smtp', new TCPCheck('smtp.example.com', 25));

// Health endpoint
router.get('/health', async (ctx) => {
  const result = await health.check();
  return ctx.json(result, result.healthy ? 200 : 503);
});

Testing

Comprehensive testing utilities for unit and integration tests.

import { AppTester, mock, assertions } from '@buenojs/bueno/testing';
import { describe, it, expect, beforeEach } from 'bun:test';

describe('UserController', () => {
  let tester: AppTester;
  
  beforeEach(async () => {
    tester = await AppTester.create(AppModule);
  });
  
  it('should create user', async () => {
    const response = await tester
      .post('/users')
      .body({ name: 'John', email: '[email protected]' })
      .execute();
    
    expect(response.status).toBe(201);
    expect(response.json()).toMatchObject({
      name: 'John',
      email: '[email protected]'
    });
  });
  
  it('should validate input', async () => {
    const response = await tester
      .post('/users')
      .body({ name: '' }) // Invalid
      .execute();
    
    expect(response.status).toBe(400);
  });
});

Frontend Support

Bueno provides first-class support for modern frontend frameworks with built-in Bun bundler integration, SSR, SSG, and Island Architecture.

Getting Started with Frontend

Option 1: Two-Stage Fullstack (Recommended)

# Creates API backend + chosen frontend automatically
bueno new my-app --template fullstack --framework react

Option 2: Add Frontend to Existing Project

bueno add:frontend react
# or with other frameworks
bueno add:frontend vue
bueno add:frontend svelte
bueno add:frontend solid

Supported Frameworks

• React - Full support with SSR and hydration, Tailwind CSS included
• Vue - Server-side rendering with Vue 3, Tailwind CSS included
• Svelte - SvelteKit-like experience, Tailwind CSS included
• SolidJS - SolidJS with SSR, Tailwind CSS included

Built-in Features

| Feature | Description | |---------|-------------| | Bun Bundler | Native Bun bundler with zero additional dependencies | | Tailwind CSS | Pre-configured with PostCSS and autoprefixer | | TypeScript | Full TypeScript support for client and server | | HMR | Hot module replacement for instant updates during development | | Dev Scripts | Convenient scripts for concurrent server/client development | | Framework-Specific | Optimized loader configurations for each framework |

Development Workflow

After creating a fullstack project, you get two development modes:

# Terminal 1: Backend API
bun run dev:server

# Terminal 2: Frontend bundler
bun run dev:client

# Or run both concurrently
bun run dev

Project Structure (Fullstack)

my-bueno-app/
├── server/              # Backend API
│   ├── main.ts
│   ├── modules/
│   └── database/
├── client/              # Frontend application
│   ├── src/
│   │   ├── main.tsx/main.ts  # Entry point
│   │   ├── App.tsx/vue/svelte # Main component
│   │   └── styles/            # Global styles (Tailwind)
│   ├── public/          # Static assets
│   ├── index.html       # HTML template
│   ├── bun.bundler.ts   # Bun bundler config
│   ├── tailwind.config.ts
│   ├── postcss.config.js
│   └── tsconfig.json
├── bueno.config.ts
├── package.json
└── tsconfig.json

Example

// client/pages/index.tsx
import { definePage } from '@buenojs/bueno/frontend';

export default definePage({
  async loader() {
    const posts = await fetch('/api/posts').then(r => r.json());
    return { posts };
  },
  
  render({ posts }) {
    return (
      <main>
        <h1>Blog Posts</h1>
        {posts.map(post => (
          <article key={post.id}>
            <h2>{post.title}</h2>
            <p>{post.excerpt}</p>
          </article>
        ))}
      </main>
    );
  }
});

Project Structure

my-bueno-app/
├── server/
│   ├── main.ts                    # Application entry point
│   ├── modules/                   # Feature modules
│   │   ├── user/
│   │   │   ├── user.module.ts
│   │   │   ├── user.controller.ts
│   │   │   ├── user.service.ts
│   │   │   └── user.dto.ts
│   │   └── auth/
│   │       ├── auth.module.ts
│   │       ├── auth.controller.ts
│   │       └── auth.guard.ts
│   ├── common/                    # Shared utilities
│   │   ├── middleware/
│   │   ├── decorators/
│   │   └── utils/
│   ├── config/                    # Configuration
│   │   ├── index.ts
│   │   └── database.ts
│   └── database/                  # Database files
│       ├── migrations/
│       ├── seeds/
│       └── schema.ts
├── client/                        # Frontend application
│   ├── pages/                     # File-based routes
│   ├── components/                # UI components
│   ├── layouts/                   # Page layouts
│   └── main.tsx                   # Entry point
├── shared/                        # Shared types and utilities
│   ├── types/
│   └── routes.ts
├── tests/                         # Test files
│   ├── unit/
│   └── integration/
├── bueno.config.ts                # Framework configuration
├── package.json
└── tsconfig.json

NPM Scripts

| Script | Description | |--------|-------------| | bun run dev | Start development server with watch mode | | bun test | Run test suite | | bun test --watch | Run tests in watch mode | | bun test --coverage | Run tests with coverage | | bun build | Build for production | | bun run typecheck | TypeScript type checking |

Framework Comparison

Bueno combines the best ideas from popular frameworks while being optimized for Bun:

| Feature | Bueno | Hono | Express | NestJS | Next.js | |---------|-------|------|---------|--------|---------| | Runtime | Bun | Multi | Node | Node | Node | | Zero Dependencies | ✅ | ✅ | ❌ | ❌ | ❌ | | Router | ✅ | ✅ | ✅ | ✅ | ✅ | | DI Container | ✅ | ❌ | ❌ | ✅ | ❌ | | Decorators | ✅ | ❌ | ❌ | ✅ | ❌ | | Built-in Validation | ✅ | ❌ | ❌ | ❌ | ❌ | | Built-in ORM | ✅ | ❌ | ❌ | ❌ | ❌ | | Built-in Caching | ✅ | ❌ | ❌ | ❌ | ❌ | | Built-in Jobs | ✅ | ❌ | ❌ | ❌ | ❌ | | SSR | ✅ | ❌ | ❌ | ❌ | ✅ | | SSG | ✅ | ❌ | ❌ | ❌ | ✅ | | WebSocket | ✅ | ✅ | Plugin | ✅ | ❌ | | CLI | ✅ | ❌ | ❌ | ✅ | ✅ |

Migration Notes:

• From Express: Similar middleware patterns, but with native async/await and TypeScript
• From Hono: Compatible routing API with additional DI and modules system
• From NestJS: Familiar decorators and module structure, but Bun-native performance
• From Next.js: Similar file-based routing and SSR capabilities, but backend-first approach

Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Setup

# Clone the repository
git clone https://github.com/buenojs/bueno.git
cd bueno

# Install dependencies
bun install

# Run tests
bun test

# Start development
bun dev

Links

• Documentation: https://buenojs.github.io
• GitHub: https://github.com/buenojs/bueno
• Issues: https://github.com/buenojs/bueno/issues
• npm: https://www.npmjs.com/package/@buenojs/bueno

License

MIT © Sivaraj D