Getting Started

bananaDB makes it easy to spin up a REST API in seconds using just a JSON file.
This guide will walk you through installation, running your first server, and exploring the API.

1. Installation

You don’t need to install bananaDB globally — you can run it directly with npx:

npx bananadb --db db.json --port 3000

Alternatively, add it to your project:

npm install --save-dev bananadb

and run it with:

npx bananadb --db db.json

2. Create a Database File

Create a file called db.json in your project root:

{
  "users": [
    { "id": 1, "name": "Alice" },
    { "id": 2, "name": "Bob" }
  ],
  "posts": []
}

3. Start the Server

Run:

npx bananadb --db db.json --port 4000

You’ll see a startup banner and the available endpoints:

🍌 BananaDB running at: http://localhost:4000
📂 Database file: db.json
🔌 Available endpoints:

/users
  GET     /users
  GET     /users/:id
  POST    /users
  PATCH   /users/:id
  DELETE  /users/:id

/posts
  GET     /posts

4. Try It Out

• GET /users → returns all users
• GET /users/1 → returns the user with ID 1
• POST /users → create a new user
• PATCH /users/1 → update an existing user
• DELETE /users/1 → remove a user

Example POST request with curl:

curl -X POST http://localhost:4000/users \\
  -H "Content-Type: application/json" \\
  -d '{"name": "Charlie"}'

Response:

{ "id": 3, "name": "Charlie" }

5. Hot Reloading

bananaDB watches your db.json file.
When you edit the file, routes and data automatically reload without restarting the server.

6. Command Line Options

• -p, --port <number> → Port to run the server (default: 3000)
• -d, --db <file> → JSON file to serve (default: db.json)
• -w, --watch <file> → Alias for --db (for json-server familiarity)
• --no-cors → Disable CORS (enabled by default)

👉 Next: Routes