Quick Start

Step 1: Clone the repository

git clone https://github.com/aashari/boilerplate-rest-api-bun.git
cd boilerplate-rest-api-bun

Step 2: Set up environment variables

# Copy the example environment file
cp .env.example .env

Note: The default values in .env should work out of the box for local development.

Step 3: Start MongoDB using Docker Compose

# Start MongoDB and Mongo Express
./api.sh mongo-up

# You can access Mongo Express at http://localhost:8081

Note: Mongo Express is a web-based MongoDB admin interface that lets you view and modify your database.

Step 4: Install dependencies

Install the project dependencies using Bun. This will also generate a bun.lock file (instead of the older bun.lockb) to ensure consistent installs across environments. Dependencies are kept up-to-date.

bun install

Step 5: Start the development server

# Start the API in the background
./api.sh start

# Check the logs
./api.sh logs

The server will start at http://localhost:3000 by default.

Note: If you want to see the server logs in real-time, press Ctrl+C to exit the logs view while keeping the server running.

Using the Helper Script

This project includes a helper script (api.sh) to make it easier to manage the API and MongoDB:

# Show available commands
./api.sh help

# Start the API
./api.sh start

# Check if the API is running
./api.sh status

# View API logs
./api.sh logs

# Stop the API
./api.sh stop

# Start MongoDB containers
./api.sh mongo-up

# Stop MongoDB containers
./api.sh mongo-down

API Endpoints

Posts

• GET /posts - Get all posts
• POST /posts - Create a new post
• GET /posts/:id - Get a post by ID
• PUT /posts/:id - Update a post by ID
• DELETE /posts/:id - Delete a post by ID

Authors

• GET /authors - Get all authors
• POST /authors - Create a new author
• GET /authors/:id - Get an author by ID
• PUT /authors/:id - Update an author by ID
• DELETE /authors/:id - Delete an author by ID

Root

• GET / - Returns a simple "hello world" message

Project Structure

.
├── src/
│   ├── _mongo/              # MongoDB connection and models
│   │   ├── index.ts         # MongoDB connection setup
│   │   ├── model.author.ts  # Author model
│   │   └── model.post.ts    # Post model
│   ├── authors/             # Author-related components
│   │   ├── dto.ts           # Author Data Transfer Object
│   │   ├── index.ts         # Author routes
│   │   └── service.ts       # Author service functions
│   ├── posts/               # Post-related components
│   │   ├── dto.ts           # Post Data Transfer Object
│   │   ├── index.ts         # Post routes
│   │   └── service.ts       # Post service functions
│   ├── index.ts             # Main application entry point
│   └── type.ts              # Common types and interfaces
├── .env.example             # Example environment variables
├── api.sh                   # Helper script for managing the API
├── docker-compose.yml       # Docker Compose configuration
├── GUIDE.md                 # Comprehensive guide for running and testing
├── package.json             # Project dependencies
└── tsconfig.json            # TypeScript configuration

Architecture Overview

Key Components

1. Entry Point (src/index.ts)

   • Sets up the Elysia server
   • Registers middleware for logging and error handling
   • Registers routes for authors and posts
   • Connects to MongoDB

2. MongoDB Connection (src/_mongo/index.ts)

   • Establishes a connection to MongoDB
   • Configures connection options based on environment variables

3. Models (src/_mongo/model.author.ts and src/_mongo/model.post.ts)

   • Define the schema for authors and posts
   • Create indexes for optimized queries
   • Establish relationships between models

4. Routes and Controllers

   • Each resource (authors, posts) has its own module with routes and service functions
   • Routes define the API endpoints
   • Service functions implement the business logic

5. Data Transfer Objects (DTOs)

   • Handle data transformations between the API and the database
   • Ensure data consistency and validation

Development

Running in Development Mode

bun run dev

This will start the server with hot reloading enabled, which means changes to your code will automatically restart the server.

Environment Variables

The following environment variables can be configured in the .env file:

• PORT: The port on which the server will run (default: 3000)
• SERVER_NAME: The name of the server (default: boilerplate-rest-api-bun)
• MONGODB_URI: The MongoDB connection URI (default: mongodb://localhost:27017)
• MONGODB_DATABASE: The MongoDB database name (default: boilerplate_db)
• NODE_ENV: The environment mode (development, production, etc.)

MongoDB Management

This project includes Mongo Express, a web-based MongoDB admin interface. When you start the Docker Compose setup, you can access Mongo Express at http://localhost:8081.

You can use Mongo Express to:

• Browse and query collections
• View, add, delete, and update documents
• Create and delete indexes
• Execute MongoDB commands

Troubleshooting

MongoDB Connection Issues

• Ensure Docker is running
• Check if the MongoDB container is running with docker ps
• Verify that the MongoDB URI in your .env file is correct
• Try restarting the MongoDB container with ./api.sh mongo-down followed by ./api.sh mongo-up

API Startup Issues

• Check the logs with ./api.sh logs or cat app.log
• Verify Bun is installed correctly
• Ensure all dependencies are installed with bun install
• Verify that nothing else is running on the configured port (default: 3000)

Authentication Issues with MongoDB

• If using authentication, ensure the username and password in .env match those in docker-compose.yml
• If not using authentication, comment out or remove MONGODB_USER and MONGODB_PASSWORD from .env

Additional Documentation

For a comprehensive guide on running and testing the API, see the GUIDE.md file. This guide includes:

• Detailed setup instructions
• Example API calls with curl
• Troubleshooting tips
• Next steps for enhancing the project

License

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

A learning-focused Node.js and TypeScript backend repository covering REST API development, Express.js server architecture, database integration, authentication, middleware, JWT, and role-based authorization.