OneJs Boilerplate

A modern, type-safe, and feature-rich framework for enterprise-grade web applications.

Documentation · Report Bug · Request Feature

---

OneJs is a high-performance boilerplate built on top of Elysia.js and Bun, implementing Hexagonal Architecture and Domain-Driven Design (DDD). It provides a robust foundation for building scalable, maintainable, and type-safe backend services.

✨ Key Features

• 🚀 Extreme Performance - Leverages Bun's runtime and Elysia's optimized router.
• 🏗️ Architectural Excellence - Strict Hexagonal Architecture and DDD principles.
• 💉 Powerful DI - Built-in Dependency Injection container with decorator support.
• 📡 Event-Driven - Seamless communication using a built-in Event Bus.
• 👷 Background Processing - Managed background tasks with BullMQ & Redis.
• 🛡️ Built-in Security - JWT and Clerk authentication strategies out of the box.
• 🗄️ Schema Harmony - Automated Prisma schema merging for multi-module projects.
• 📝 Smart CLI - Instant scaffolding of apps and domain modules.

🛠️ Tech Stack

Category	Technology
Runtime	Bun
Web Framework	Elysia.js
Database/ORM	PostgreSQL & Prisma
Task Queue	BullMQ & Redis
Code Quality	Biome
Environment	Docker / Podman

🏗️ Architecture at a Glance

OneJs enforces a clear separation of concerns, ensuring your domain logic remains pure and decoupled from infrastructure details.

graph TD
    subgraph Infrastructure [Infrastructure Layer]
        Controllers[Controllers / API]
        Persistence[Prisma / Repositories]
        External[External Adapters]
    end

    subgraph Application [Application Layer]
        UseCases[Use Cases]
        Services[Application Services]
    end

    subgraph Domain [Domain Layer]
        Entities[Entities]
        ValueObjects[Value Objects]
        Events[Domain Events]
    end

    Infrastructure --> Application
    Application --> Domain
    Infrastructure --> Domain

Loading

🚀 Quick Start

1. Clone & Install

   git clone <repository-url>
   cd eyjs-boilerplate
   bun install

2. Initialize Your Project

   bun run init

   Follow the interactive prompts to choose which components (API, Admin, Worker) and examples you want to keep. This will clean up the boilerplate for your specific needs.

3. Launch Dev Environment

   bun start:api:dev

   This starts the DB, merges schemas, runs migrations, and launches the server.

🛠️ Usage & Scaffolding

Project Templates

OneJs supports different application types that you can choose during bun run init:

• API: High-performance backend using Elysia.js.
• Admin: Modern dashboard built with Next.js and Shadcn UI.
• Worker: Background task processor using BullMQ and Redis.

Scaffolding New Modules

To create new business logic modules following hexagonal architecture:

bun create-app <module-name>

This generates a complete folder structure including Domain, Application, and Infrastructure layers.

📖 Documentation

Explore our comprehensive guides to master OneJs:

• Overview & Setup
• Hexagonal Architecture Deep Dive
• Dependency Injection & Core
• Routing & Controllers
• Database & Persistence
• Events & Background Jobs
• Authentication & Security
• CLI Tool Usage

🤝 Contributing

Contributions are what make the open-source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git checkout -b feature/AmazingFeature)
5. Open a Pull Request

📄 License

Distributed under the MIT License. See LICENSE for more information.