VibeX

Appearance

VibeX ​

The Revolutionary JSON-Based Backend Framework for Bun & TypeScript.

  • 🚀 Rapid API development
  • 🧩 JSON-driven entities & controllers
  • 🔒 Built-in authentication & validation
  • ⚡️ Bun-native performance
  • 🛠️ CLI for code generation, migrations, and more
  • 🧪 Built-in testing support
  • 📦 Modular, extensible, and Bun-native

Why VibeX? ​

VibeX is designed for developers who want to build robust, scalable, and maintainable backends with minimal boilerplate. It leverages Bun and TypeScript for top performance and developer experience.

  • JSON-first: Define entities, controllers, and routes in JSON or TypeScript
  • Convention over configuration: Sensible defaults, but fully customizable
  • Database agnostic: SQLite, MySQL, PostgreSQL, MariaDB, and more via MikroORM
  • Powerful hooks & middleware: Easily extend and customize behavior
  • Secure by default: Built-in JWT authentication, password hashing, and validation

Quick Start ​

bash
bun create vibe@latest my-app
cd my-app
bun install
bun run dev

Project Structure ​

my-app/
├── src/
│   ├── entities/
│   ├── controller/
│   ├── middleware/
│   ├── hooks/
│   └── index.ts
├── vibe.config.ts
├── cli/
├── migrations/
└── tests/
  • entities/: Data models (JSON or TypeScript)
  • controller/: API logic (JSON or TypeScript)
  • middleware/: Custom middleware
  • hooks/: Lifecycle hooks
  • vibe.config.ts: Project configuration
  • cli/: CLI commands
  • migrations/: Database migrations
  • tests/: Unit and e2e tests

Core Concepts ​

Entities ​

Define your data models in JSON or TypeScript. Supports validation, defaults, and (soon) relations.

Controllers ​

Describe your API endpoints and logic. Supports RESTful routes, validation, and hooks.

Middleware ​

Add custom logic for authentication, CORS, logging, etc. Use built-in or custom middleware.

Hooks ​

Run code before/after entity/controller actions (e.g., beforeCreate, afterUpdate).

Database ​

Configure SQLite, MySQL, PostgreSQL, MariaDB, and more. Use MikroORM for migrations and queries.

Authentication ​

JWT-based authentication and password hashing out of the box. Easily add custom providers.

CLI ​

Powerful CLI for code generation, migrations, testing, and more.

Code Generation ​

Generate entities, controllers, and tests with a single command.

Testing ​

Built-in support for Bun's test runner. Write unit and e2e tests easily.

Example: Defining an Entity (TypeScript) ​

ts
// entities/user.entity.ts
export class User {
  id: number;
  name: string;
  email: string;
  password: string;
}

Example: Defining an Entity (JSON) ​

json
{
  "name": "Todo",
  "fields": {
    "id": { "type": "number", "primary": true },
    "title": { "type": "string" },
    "completed": { "type": "boolean", "default": false }
  }
}

Example: Controller (TypeScript) ​

ts
// controller/todos.controller.ts
export class TodosController {
  async findAll(ctx) { /* ... */ }
  async create(ctx) { /* ... */ }
}

Example: Controller (JSON) ​

json
{
  "name": "TodosController",
  "routes": {
    "GET /todos": "findAll",
    "POST /todos": "create"
  }
}

Example: Middleware ​

ts
// middleware/auth.ts
export default function auth(ctx, next) {
  // Check authentication
  return next();
}

Example: Hook ​

ts
// hooks/todos/beforeCreate.ts
export default async function beforeCreate(ctx) {
  // Custom logic before creating a todo
}

Example: vibe.config.ts ​

ts
export default {
  port: 3000,
  database: {
    type: 'sqlite',
    url: 'sqlite://./todo-app.db',
  },
  entities: 'src/entities',
  controllers: 'src/controller',
  middleware: 'src/middleware',
  jwtSecret: 'your-secret',
};

Example: Running Migrations ​

bash
bun run cli migrate

Example: Generating Code ​

bash
bun run cli generate entity User
bun run cli generate controller Todo

Example: Testing ​

bash
bun test

Learn More ​

Developer Guide Highlights ​

Entity Design ​

  • Use descriptive, lowercase names for entities and fields.
  • Leverage field types: string, email, password, number, boolean, date, uuid, json, enum.
  • Use options like required, unique, default, length, enum, index, and comment for clarity and validation.
  • Support for relationships: one-to-many, many-to-many, and advanced features like indexes, soft delete, and timestamps.

Controller Design ​

  • RESTful, auto-CRUD actions: list, read, create, update, delete, count.
  • Route-level authentication and role-based access control.
  • Request validation for body, params, and query.
  • Pagination, filtering, sorting, and response shaping.
  • Rate limiting per route or globally.

Custom Hooks ​

  • Write business logic in TypeScript hooks for before/after create, update, delete, and custom actions.
  • Access context: request, response, entity, data, db, services, user, config, utils.
  • Use hooks for validation, transformation, side effects (emails, storage), and error handling.

Authentication & Security ​

  • JWT authentication with strong secrets and expiration.
  • Password hashing with bcrypt and validation for strength.
  • Middleware for CORS, rate limiting, and security headers.
  • Role-based access control in controllers and routes.

Database Integration ​

  • Configure SQLite (via MikroORM), PostgreSQL, MySQL, MariaDB, etc.
  • Use MikroORM migrations for schema changes.
  • Advanced queries and transactions in hooks.
  • Caching and performance optimizations.

Testing Strategies ​

  • Unit test hooks and utilities with Bun's test runner.
  • Integration test API endpoints and database logic.
  • E2E test full user workflows.
  • Organize tests by type: unit, integration, e2e.

Deployment & Best Practices ​

  • Use environment variables for secrets and config.
  • Docker and docker-compose for production deployments.
  • Monitor with health checks and metrics.
  • Write self-documenting code and leverage auto-generated API docs.

For more, see the detailed guides in each section of the docs. Start simple, use auto-CRUD, and add custom hooks and security as you scale!