Igniter.js Starter: Bun REST API

Welcome to the Igniter.js starter for building high-performance, type-safe REST APIs with Bun. This template provides a robust and scalable foundation for creating modern back-end services.

Features

• High-Performance API Server

  Built on Bun, one of the fastest JavaScript runtimes available.
• Type-Safe from the Ground Up

  Powered by Igniter.js, ensuring a strongly-typed codebase that is easy to maintain and refactor.
• Feature-Based Architecture

  A scalable project structure that organizes code by business domain, not technical layers.
• Ready-to-Use Services

  Pre-configured examples for: [object Object]
• Database Ready

  Comes with Prisma set up for seamless database integration.
• Auto-Generated Type-Safe Client

  Even as a REST API, you can generate a fully-typed client ([object Object]) for consumption by other TypeScript services or a separate front-end application.

Prerequisites

Before you begin, ensure you have the following installed:

• Bun (v1.0 or higher)
• A running Redis instance (for caching and background jobs).
• A PostgreSQL database (or you can configure Prisma for a different one).

Getting Started

Follow these steps to get your project up and running:

1. Clone the Repository

   Code

   git clone https://github.com/felipebarcelospro/igniter-js.git
   cd igniter-js/apps/starter-bun-rest-api
   

2. Install Dependencies

   Code

   bun install
   

3. Configure Environment Variables Create a .env file in the root of this starter (igniter-js/apps/starter-bun-rest-api/.env) and add your database and Redis connection URLs:

   Code

   # .env
   DATABASE_URL="postgresql://user:password@localhost:5432/mydatabase?schema=public"
   REDIS_URL="redis://127.0.0.1:6379"
   

4. Run Database Migrations

   Code

   bunx prisma db push
   

5. Run the Development Server

   Code

   bun run dev
   

   This command starts the Bun server with hot-reloading enabled. Your API will be available at http://localhost:3000/api/v1.

How It Works

This starter is a pure API server.

1. The Bun Server (src/index.ts)

The src/index.ts file is the main entry point. It uses Bun's native serve function to handle incoming requests. All requests to /api/v1/* are forwarded directly to the Igniter.js API router handler.

2. The Igniter.js API Layer

The back-end API is defined using Igniter.js.

• Initialization (src/igniter.ts)

  This is where the core Igniter instance is created and configured with adapters for the store (Redis), jobs (BullMQ), logging, and telemetry.
• Router (src/igniter.router.ts)

  This file defines all API controllers. The starter includes an [object Object] with several actions demonstrating core features.
• Controllers (src/features/example/controllers/example.controller.ts)

  Controllers group related API actions. The example shows how to implement queries (GET) and mutations (POST), interact with the cache, and schedule background jobs.
• Services (src/services/)

  This directory contains the initialization logic for external services like the Redis client, Prisma client, and the Igniter.js adapters that use them.

Project Structure

The project follows a feature-based architecture to promote scalability and separation of concerns.

src/
├── features/             # Business logic, grouped by feature
│   └── example/
│       └── controllers/  # API endpoint definitions
├── services/             # Service initializations (Redis, Prisma, etc.)
├── igniter.ts            # Igniter.js core instance
├── igniter.client.ts     # Auto-generated type-safe API client (for consumers)
├── igniter.context.ts    # Application context definition
├── igniter.router.ts     # Main API router
└── index.ts              # Application entry point (Bun server)

Example API Endpoints

This starter comes with a pre-built example controller to demonstrate key features.

• Health Check

  Code

  curl http://localhost:3000/api/v1/example/
  

• Cache Demonstration

  Code

  # First request (live data)
  curl http://localhost:3000/api/v1/example/cache/my-key
  # Second request (cached data)
  curl http://localhost:3000/api/v1/example/cache/my-key
  

• Schedule a Background Job

  Code

  curl -X POST -H "Content-Type: application/json" \
    -d '{"message": "Hello from curl"}' \
    http://localhost:3000/api/v1/example/schedule-job
  

• List Jobs

  Code

  curl http://localhost:3000/api/v1/example/jobs
  

Available Scripts

• bun run dev: Starts the development server with hot-reloading.
• bun run start: Starts the application in production mode.

Further Learning

To learn more about Igniter.js and its powerful features, check out the official documentation:

• Igniter.js GitHub Repository
• Official Documentation
• Core Concepts
• Store (Redis)
• Queues (BullMQ)

License

This starter is licensed under the MIT License.