Bun adalah JavaScript runtime yang dirancang untuk menjalankan aplikasi server-side dan tooling dengan performa tinggi serta API yang praktis. Salah satu fitur yang paling mudah dicoba adalah kemampuan membuat HTTP server tanpa perlu memasang framework tambahan. Untuk kebutuhan pengenalan, Bun sudah menyediakan API yang cukup sederhana untuk menerima request dan mengembalikan response.

Pada artikel ini, kita akan fokus pada hal yang paling dasar: membuat server HTTP sederhana menggunakan Bun, menangani request ke beberapa endpoint, lalu mengembalikan response dalam bentuk teks maupun JSON. Contoh yang digunakan sengaja dibuat minimal agar mudah dipahami, tetapi tetap mengikuti pola yang rapi dan realistis untuk tahap awal belajar.

Apa Itu Bun dan Kapan Cocok Digunakan?

Bun adalah runtime JavaScript dan TypeScript yang bisa digunakan untuk menjalankan script, mengelola package, dan membuat aplikasi backend. Untuk topik ini, yang penting dipahami adalah Bun memiliki API bawaan untuk membuat server HTTP melalui Bun.serve(). Artinya, Anda tidak harus langsung menggunakan framework seperti Express, Hono, atau Fastify hanya untuk membuat endpoint sederhana.

Pendekatan ini cocok jika Anda ingin:

  • Memahami dasar request dan response HTTP di Bun.
  • Membuat prototipe API kecil dengan cepat.
  • Menguji endpoint sederhana tanpa menambah dependensi.
  • Belajar bagaimana runtime menangani request secara langsung.

Namun, untuk aplikasi yang semakin besar, Anda tetap perlu mempertimbangkan struktur routing, validasi input, logging, authentication, dan error handling yang lebih sistematis. Jadi, artikel ini sengaja berhenti di level pengenalan API dasar, bukan arsitektur backend penuh.

Persiapan Lingkungan

Sebelum menulis kode, pastikan Bun sudah terpasang di sistem Anda. Anda bisa memeriksa instalasinya dengan perintah berikut:

bun --version

Jika perintah tersebut menampilkan nomor versi, berarti Bun sudah siap digunakan. Selanjutnya, buat folder proyek sederhana:

mkdir bun-http-server
cd bun-http-server

Untuk tutorial dasar ini, Anda belum perlu memasang package tambahan. Kita cukup membuat satu file JavaScript, misalnya server.js.

Membuat HTTP Server Paling Dasar

Inti pembuatan server di Bun adalah memanggil Bun.serve() dan menyediakan fungsi fetch untuk menangani setiap request yang masuk. Konsep ini mirip dengan API Request/Response modern berbasis Web Standard.

Buat file server.js dengan isi berikut:

const server = Bun.serve({
  port: 3000,
  fetch(request) {
    return new Response("Halo dari Bun!", {
      status: 200,
      headers: {
        "Content-Type": "text/plain; charset=utf-8",
      },
    });
  },
});

console.log(`Server berjalan di http://localhost:${server.port}`);

Mari kita bedah bagian pentingnya:

  • Bun.serve({ ... }) membuat HTTP server baru.
  • port: 3000 menentukan server mendengarkan koneksi pada port 3000.
  • fetch(request) adalah handler yang dipanggil setiap kali ada request masuk.
  • new Response(...) digunakan untuk mengembalikan response ke client.
  • Header Content-Type memberi tahu browser atau client bahwa isi response berupa teks biasa dengan encoding UTF-8.

Kenapa API ini terasa sederhana? Karena Bun menggunakan model yang dekat dengan API Web modern. Daripada menggunakan objek khusus seperti req dan res ala framework lama, Anda bekerja langsung dengan objek Request dan Response. Pendekatan ini membuat kode lebih konsisten dengan ekosistem Web API.

Menjalankan Server

Setelah file dibuat, jalankan server dengan perintah:

bun run server.js

Jika berhasil, Anda akan melihat output seperti:

Server berjalan di http://localhost:3000

Buka browser dan akses:

http://localhost:3000

Anda seharusnya melihat teks:

Halo dari Bun!

Menangani Endpoint Berbeda

Server dasar di atas selalu mengembalikan response yang sama untuk semua request. Dalam praktik nyata, kita biasanya ingin memberi response berbeda berdasarkan path, misalnya / untuk halaman utama dan /api/hello untuk data JSON.

Ubah isi server.js menjadi seperti berikut:

const server = Bun.serve({
  port: 3000,
  fetch(request) {
    const url = new URL(request.url);

    if (url.pathname === "/") {
      return new Response("Selamat datang di server Bun", {
        headers: {
          "Content-Type": "text/plain; charset=utf-8",
        },
      });
    }

    if (url.pathname === "/api/hello") {
      const data = {
        message: "Halo, JSON dari Bun!",
        method: request.method,
      };

      return Response.json(data);
    }

    return new Response("Not Found", {
      status: 404,
      headers: {
        "Content-Type": "text/plain; charset=utf-8",
      },
    });
  },
});

console.log(`Server berjalan di http://localhost:${server.port}`);

Ada beberapa hal penting pada contoh ini:

  • new URL(request.url) digunakan untuk mem-parsing URL request agar kita bisa membaca pathname.
  • Jika path adalah /, server mengembalikan teks biasa.
  • Jika path adalah /api/hello, server mengembalikan JSON melalui Response.json().
  • Jika path tidak cocok, server mengembalikan status 404.

Kenapa penting mengembalikan status 404 untuk endpoint yang tidak ada? Karena client perlu tahu bahwa resource yang diminta memang tidak ditemukan. Kesalahan umum pemula adalah selalu mengembalikan status 200, padahal itu membuat debugging API menjadi membingungkan.

Mengembalikan Response JSON

Untuk response JSON, Bun mendukung penggunaan Response.json(). Ini lebih ringkas daripada menulis:

return new Response(JSON.stringify(data), {
  headers: {
    "Content-Type": "application/json",
  },
});

Secara praktik, Response.json() lebih aman dan lebih jelas dibaca karena niat kodenya langsung terlihat: kita sedang mengirim JSON.

Menguji Endpoint dengan Browser dan curl

Setelah server berjalan, Anda bisa menguji endpoint dengan dua cara paling sederhana.

Uji lewat Browser

Untuk endpoint teks biasa, buka URL berikut di browser:

  • http://localhost:3000/
  • http://localhost:3000/api/hello

Browser akan menampilkan isi response secara langsung. Untuk endpoint JSON, sebagian browser juga akan memformat JSON agar lebih mudah dibaca.

Uji lewat curl

curl berguna untuk menguji endpoint dari terminal, terutama saat Anda ingin melihat header, status code, atau mengirim method tertentu.

Contoh request ke root endpoint:

curl http://localhost:3000/

Contoh request ke endpoint JSON:

curl http://localhost:3000/api/hello

Jika ingin melihat detail response termasuk status dan header:

curl -i http://localhost:3000/api/hello

Output akan memperlihatkan hal seperti:

HTTP/1.1 200 OK
content-type: application/json;charset=utf-8

{"message":"Halo, JSON dari Bun!","method":"GET"}

Untuk menguji endpoint yang tidak ada:

curl -i http://localhost:3000/tidak-ada

Anda seharusnya menerima status 404.

Menangani Method Request Sederhana

Walaupun tutorial ini tidak membahas API kompleks, ada baiknya memahami bahwa request HTTP juga memiliki method seperti GET, POST, PUT, atau DELETE. Kita bisa memeriksa request.method untuk membedakan perilaku server.

Berikut contoh sederhana untuk menerima GET dan menolak method lain pada endpoint tertentu:

const server = Bun.serve({
  port: 3000,
  fetch(request) {
    const url = new URL(request.url);

    if (url.pathname === "/api/hello") {
      if (request.method !== "GET") {
        return new Response("Method Not Allowed", {
          status: 405,
          headers: {
            "Content-Type": "text/plain; charset=utf-8",
          },
        });
      }

      return Response.json({
        message: "Halo dari endpoint GET",
      });
    }

    return new Response("Not Found", { status: 404 });
  },
});

console.log(`Server berjalan di http://localhost:${server.port}`);

Status 405 Method Not Allowed lebih tepat daripada 404 jika endpoint-nya ada tetapi method yang dipakai tidak didukung. Ini contoh kecil, tetapi penting untuk membentuk kebiasaan API yang benar sejak awal.

Kesalahan Umum dan Tips Debugging

Saat baru belajar Bun, ada beberapa masalah yang sering muncul:

1. Port Sudah Dipakai

Jika port 3000 sedang digunakan proses lain, server bisa gagal start. Solusinya:

  • Matikan proses yang menggunakan port tersebut, atau
  • Ganti ke port lain, misalnya 3001.

2. Lupa Memeriksa Pathname

Beberapa pemula langsung membandingkan request.url dengan string seperti "/api/hello". Ini biasanya gagal karena request.url berisi URL penuh, misalnya http://localhost:3000/api/hello. Gunakan:

const url = new URL(request.url);
console.log(url.pathname);

3. Content-Type Tidak Sesuai

Jika mengirim JSON tetapi header tidak benar, beberapa client bisa salah menafsirkan isi response. Untuk JSON, gunakan Response.json() atau set Content-Type: application/json secara eksplisit.

4. Semua Error Dibalas 200

Biasakan memakai status code yang tepat:

  • 200 untuk sukses.
  • 404 jika path tidak ditemukan.
  • 405 jika method tidak diizinkan.
  • 500 jika terjadi error internal server.

Status code yang benar sangat membantu saat integrasi dengan frontend, tool API, atau monitoring.

5. Menambahkan Logging Sederhana

Untuk melihat request yang masuk, Anda bisa menambahkan logging ringan:

console.log(request.method, new URL(request.url).pathname);

Ini cukup berguna saat Anda ingin memastikan route mana yang benar-benar dipanggil oleh browser atau curl.

Batasan Pendekatan Server Minimal

Membuat server langsung dengan Bun.serve() adalah cara yang bagus untuk belajar, tetapi ada trade-off yang perlu dipahami:

  • Routing dilakukan manual dengan if atau switch, sehingga cepat berantakan jika endpoint bertambah banyak.
  • Validasi request belum terstruktur.
  • Middleware seperti autentikasi, logging terpusat, atau CORS perlu ditangani sendiri.
  • Pengelolaan error lebih mudah terlewat jika aplikasi mulai kompleks.

Karena itu, pendekatan ini paling cocok untuk pengenalan, eksperimen, utilitas kecil, atau API internal yang sangat sederhana. Saat kebutuhan bertambah, Anda bisa mempertimbangkan menyusun abstraksi sendiri atau memakai framework yang kompatibel dengan Bun.

Catatan: Memahami server minimal tetap penting meskipun nantinya Anda memakai framework. Dengan mengetahui cara request dan response bekerja di level dasar, Anda akan lebih mudah membaca dokumentasi, debugging, dan memahami perilaku framework di balik layar.

Penutup

Bun menyediakan cara yang sangat langsung untuk membuat HTTP server sederhana. Dengan Bun.serve(), Anda bisa menerima request, memeriksa URL dan method, lalu mengembalikan response teks atau JSON tanpa dependensi tambahan. Ini menjadikan Bun nyaman untuk belajar dasar HTTP server maupun membuat prototipe cepat.

Dalam tutorial ini, kita sudah membahas cara membuat server minimal, menambahkan beberapa endpoint, mengembalikan teks dan JSON, menjalankan server, serta mengujinya lewat browser dan curl. Langkah berikutnya yang bisa Anda eksplorasi adalah menerima body request, membaca query parameter, menambahkan header khusus, atau memisahkan handler ke file terpisah agar kode lebih rapi.

Selama kebutuhan Anda masih sederhana, API dasar Bun sudah sangat cukup. Yang paling penting adalah membangun kebiasaan yang benar sejak awal: gunakan status code yang sesuai, tetapkan header yang tepat, dan uji endpoint secara eksplisit.