Cara Menulis README.md yang Profesional untuk Project Backend Node.js

Di artikel sebelumnya, kita sudah merangkum seluruh Todo List API jadi satu boilerplate utuh. Tapi ada satu hal penting yang belum kita punya: penjelasan tertulis tentang project ini. Bayangkan kamu membagikan link repository ke temanmu, dosen pembimbing, atau tim HRD saat magang — hal pertama yang mereka lihat bukan kode di dalam folder src/, melainkan satu file bernama README.md.

Artikel ini akan membahas anatomi README yang baik dan langsung mempraktikkannya untuk Todo List API, termasuk cara mendokumentasikan environment variable dengan benar — termasuk variabel NODE_ENV yang menentukan apakah aplikasi berjalan dalam mode development, testing, atau production.

Artikel ini melengkapi boilerplate dari artikel pertama hingga kesembilan. Setelah ini, seri akan ditutup dengan Panduan Push Project ke GitHub.

1. Kenapa README Itu Penting?

Analogi: README itu ibarat papan nama dan brosur di depan pintu masuk sebuah ruangan lab sekolah. Sebelum orang masuk dan mengutak-atik alat-alat di dalam (kode sungguhan), papan nama itu sudah menjawab pertanyaan paling dasar: ruangan ini isinya apa, siapa yang boleh pakai, alat apa saja yang perlu dibawa sebelum masuk, dan langkah apa yang harus diikuti supaya tidak salah pakai alat. Tanpa papan nama itu, setiap orang yang datang harus bertanya langsung ke penjaga lab (developer aslinya) satu per satu — melelahkan buat kedua belah pihak.

README yang baik menjawab pertanyaan-pertanyaan berikut tanpa orang lain perlu membaca kode sumber atau bertanya langsung:

• Project ini sebenarnya untuk apa?

• Teknologi apa saja yang dipakai?

• Apa saja syarat sebelum bisa menjalankannya (versi Node.js, MongoDB, dll)?

• Bagaimana cara install dan menjalankannya dari nol?

• Environment variable apa saja yang wajib diisi?

• Bagaimana cara menjalankan test?

• Di mana dokumentasi API lengkapnya?

2. Menulis README.md untuk Todo List API

Buat file README.md di root project (sejajar dengan package.json). Berikut isinya secara lengkap:

# Todo List API

API backend untuk aplikasi Todo List, dibangun sebagai boilerplate belajar backend Node.js: struktur folder Controller-Service-Model, middleware, autentikasi JWT, proteksi API Key, validasi input, pagination, automated testing, dan dokumentasi Swagger.
![Node.js](https://img.shields.io/badge/Node.js-18%2B-339933?logo=nodedotjs&logoColor=white)
![Express](https://img.shields.io/badge/Express-4.x-000000?logo=express&logoColor=white)
![MongoDB](https://img.shields.io/badge/-MongoDB-4DB33D?style=flat&logo=mongodb&logoColor=FFFFFF)
![Tests](https://img.shields.io/badge/tests-passing-brightgreen)

## Daftar Isi

- [Fitur](#fitur)
- [Teknologi yang Dipakai](#teknologi-yang-dipakai)
- [Struktur Project](#struktur-project)
- [Persyaratan](#persyaratan)
- [Instalasi](#instalasi)
- [Environment Variables](#environment-variables)
- [Menjalankan Project](#menjalankan-project)
- [Menjalankan Test](#menjalankan-test)
- [Dokumentasi API](#dokumentasi-api)
- [Referensi Endpoint Singkat](#referensi-endpoint-singkat)
- [Lisensi](#lisensi)

## Fitur

- CRUD Todo dengan struktur Controller-Service-Model
- Autentikasi JWT dan otorisasi berbasis role (RBAC)
- Proteksi endpoint machine-to-machine dengan API Key
- Validasi input di setiap endpoint
- Pagination, filtering, dan sorting pada data list
- Global error handling dengan status code yang konsisten
- Automated test dengan Jest dan Supertest
- Dokumentasi interaktif dengan Swagger UI

## Teknologi yang Dipakai

- **Runtime:** Node.js
- **Framework:** Express.js
- **Database:** MongoDB dengan Mongoose
- **Autentikasi:** JSON Web Token (JWT), bcryptjs
- **Validasi:** express-validator
- **Testing:** Jest, Supertest, mongodb-memory-server
- **Dokumentasi:** swagger-jsdoc, swagger-ui-express

## Struktur Project

```
src/
├── config/ # Koneksi database & konfigurasi Swagger
├── middlewares/ # Logger, auth, error handler, validasi, dll
├── validators/ # Aturan validasi input per resource
├── models/ # Schema Mongoose
├── services/ # Business logic
├── controllers/ # Penghubung HTTP request/response ke service
├── routes/ # Definisi endpoint
├── utils/ # AppError, catchAsync
├── app.js # Konfigurasi Express
└── server.js # Entry point aplikasi
```

## Persyaratan

Sebelum menjalankan project ini, pastikan sudah terinstall:

- Node.js versi 18 ke atas
- MongoDB (lokal) atau akun MongoDB Atlas
- npm (sudah termasuk saat install Node.js)

## Minimum Requirements

Pastikan environment pengembangan memenuhi spesifikasi minimum berikut:

| Software       | Versi Minimum |
| -------------- | ------------- |
| Node.js        | 18.x          |
| npm            | 9.x           |
| MongoDB        | 6.x           |
| RAM            | 2 GB          |
| Storage Kosong | 500 MB        |

Sistem operasi yang didukung:

- Windows 10/11
- Linux (Ubuntu 22.04+ direkomendasikan)
- macOS 12+

## Instalasi

```bash
git clone https://github.com/username-kamu/todo-api.git
cd todo-api
npm install
```

## Environment Variables

Salin file `.env.example` menjadi `.env`, lalu sesuaikan nilainya:

```bash
cp .env.example .env
```

| Variable           | Wajib | Contoh Nilai                            | Keterangan                                                    |
| ------------------ | ----- | --------------------------------------- | ------------------------------------------------------------- |
| `PORT`             | Tidak | `3000`                                  | Port server, default `3000` jika tidak diisi                  |
| `MONGODB_URI`      | Ya    | `mongodb://127.0.0.1:27017/todo_api_db` | Connection string MongoDB                                     |
| `NODE_ENV`         | Ya    | `development` / `test` / `production`   | Menentukan mode aplikasi berjalan (lihat penjelasan di bawah) |
| `JWT_SECRET`       | Ya    | string acak & panjang                   | Kunci rahasia untuk menandatangani token JWT                  |
| `JWT_EXPIRES_IN`   | Ya    | `1d`                                    | Masa berlaku token JWT                                        |
| `EXTERNAL_API_KEY` | Ya    | string acak & panjang                   | Kunci akses untuk endpoint `/api/stats`                       |

## Menjalankan Project

```bash

# Mode development (auto-restart saat ada perubahan kode)

npm run dev

# Mode production

npm start
```

Server berjalan di `http://localhost:3000` (atau sesuai `PORT` yang diisi di `.env`).

## Menjalankan Test

```bash
npm test
```

Test memakai `mongodb-memory-server`, jadi tidak akan menyentuh database development sungguhan.

## Dokumentasi API

Dokumentasi interaktif tersedia di `http://localhost:3000/api-docs` setelah server dijalankan.

## Referensi Endpoint Singkat

| Method | Endpoint             | Autentikasi | Keterangan                         |
| ------ | -------------------- | ----------- | ---------------------------------- |
| POST   | `/api/auth/register` | -           | Registrasi user baru               |
| POST   | `/api/auth/login`    | -           | Login, mendapatkan token JWT       |
| POST   | `/api/todos`         | JWT         | Membuat todo baru                  |
| GET    | `/api/todos`         | JWT         | Mengambil daftar todo (pagination) |
| GET    | `/api/todos/:id`     | JWT         | Mengambil satu todo                |
| PUT    | `/api/todos/:id`     | JWT         | Mengupdate todo                    |
| DELETE | `/api/todos/:id`     | JWT         | Menghapus todo                     |
| GET    | `/api/stats/summary` | API Key     | Ringkasan statistik todo           |

Untuk detail lengkap tiap endpoint (skema request/response, contoh, dan kemungkinan error), lihat dokumentasi Swagger di atas.

## Lisensi

Project ini dirilis di bawah lisensi **MIT License**.

Anda bebas untuk:

- Menggunakan untuk kebutuhan pribadi maupun komersial
- Mempelajari source code
- Memodifikasi project
- Mendistribusikan ulang project

Dengan syarat tetap menyertakan copyright dan lisensi asli.

Untuk lihat hasil preview kode .md bisa menggunakan website seperti : https://markdownlivepreview.com

Penjelasan teknis:

• Badge (![Node.js](https://img.shields.io/badge/...)) di bagian paling atas dibuat lewat layanan shields.io — ini bukan gambar statis yang perlu kamu upload manual, tapi URL yang otomatis merender jadi label berwarna. Badge ini bukan cuma estetika: sekilas pandang, orang langsung tahu versi Node.js dan status testing project tanpa harus scroll ke bawah.

• [Fitur](#fitur) di bagian Daftar Isi adalah link internal ke heading ## Fitur di bawahnya — GitHub otomatis mengubah tiap heading markdown jadi “anchor” yang bisa dituju, dengan aturan: huruf kecil semua, spasi diganti tanda hubung. Fitur ini sangat membantu untuk README yang panjang seperti ini, supaya orang bisa lompat langsung ke bagian yang mereka butuhkan.

• Bagian Struktur Project sengaja hanya menampilkan garis besar folder src/ (bukan detail tiap file di dalamnya) — README bertugas memberi peta besar, sementara detail teknis tiap file cukup dijelaskan lewat komentar kode atau dokumentasi Swagger, supaya README tidak kepanjangan dan cepat basi setiap ada file baru ditambahkan.

• Tabel Environment Variables mencantumkan kolom Wajib secara eksplisit — ini penting supaya orang yang baru clone project langsung tahu variabel mana yang harus diisi (kalau tidak, aplikasi akan process.exit(1) seperti yang kita buat di db.js pada artikel kedua) dan mana yang punya nilai default aman (seperti PORT).

3. NODE_ENV: Perbedaan Development, Test, dan Production

Analogi: anggap NODE_ENV itu seperti status seragam yang dipakai di sekolah tergantung acaranya — seragam harian biasa untuk hari sekolah normal (development), seragam olahraga khusus saat ujian praktik (test), dan seragam upacara resmi saat ada tamu kepala dinas datang (production). Aturan dan perilaku yang berlaku bisa berbeda tergantung “seragam” mana yang sedang dipakai, meskipun orangnya (kodenya) tetap sama.

Sepanjang seri ini, kita sebenarnya sudah beberapa kali memakai NODE_ENV tanpa membahasnya secara khusus. Mari kita kumpulkan kembali di sini:

3.1 Di errorHandler (Artikel #2 dan #3)

// Cuplikan dari src/middlewares/errorHandler.middleware.js
res.status(statusCode).json({
  success: false,
  message,
  // Stack trace hanya ditampilkan saat development, jangan di production
  stack: process.env.NODE_ENV === "development" ? err.stack : undefined,
});

Penjelasan teknis: stack trace berisi detail teknis di baris kode mana error terjadi — sangat membantu untuk debugging saat development, tapi berbahaya kalau bocor ke client di production, karena bisa membocorkan struktur folder, nama package yang dipakai, bahkan potongan kode internal ke pihak yang tidak seharusnya tahu. Baris ini memastikan detail sensitif itu hanya muncul saat NODE_ENV=development, dan otomatis disembunyikan (undefined, sehingga tidak ikut dikirim di response JSON) untuk nilai NODE_ENV apa pun selain itu, termasuk production.

3.2 Di server.js (Artikel #2)

// Cuplikan dari src/server.js
app.listen(PORT, () => {
  console.log(`Server running on http://localhost:${PORT}`);
  console.log(`Environment: ${process.env.NODE_ENV}`);
});

Penjelasan teknis: log ini sederhana tapi penting saat production — kalau suatu hari server berjalan dengan perilaku aneh (misalnya stack trace error tiba-tiba muncul ke user), log startup ini adalah tempat pertama untuk memastikan NODE_ENV benar-benar sudah diset production di server hosting, bukan cuma lupa di-set sehingga jatuh ke nilai default.

3.3 Tiga Nilai NODE_ENV yang Kita Pakai

3.4 Menyiapkan .env untuk Production

Saat nanti kamu deploy aplikasi ini ke server sungguhan (akan dibahas lebih lanjut soal hosting di seri artikel lain), pastikan nilai .env di server production berbeda dari yang dipakai di laptop:

# Contoh .env untuk PRODUCTION — jangan pernah pakai nilai development di sini
PORT=3000
MONGODB_URI=mongodb+srv://user:password@cluster.mongodb.net/todo_api_db
NODE_ENV=production

JWT_SECRET=ganti-dengan-secret-baru-yang-berbeda-dari-development
JWT_EXPIRES_IN=1d

EXTERNAL_API_KEY=ganti-dengan-api-key-baru-yang-berbeda-dari-development

Penjelasan teknis dan praktik baik:

• Jangan pernah memakai JWT_SECRET atau EXTERNAL_API_KEY yang sama antara development dan production. Kalau salah satu bocor (misalnya lewat laptop yang hilang), dampaknya tidak akan menjalar ke sistem production.

• MONGODB_URI di production biasanya mengarah ke database terpisah dari yang dipakai untuk development/testing — supaya data latihan/testing tidak pernah tercampur dengan data pengguna sungguhan. Perhatikan juga formatnya berbeda: mongodb+srv:// untuk MongoDB Atlas (cloud), bukan mongodb://127.0.0.1 yang hanya berlaku di komputer lokal.

• Sebagian besar platform hosting (Railway, Render, Vercel, VPS dengan PM2, dll) punya cara tersendiri untuk mengisi environment variable lewat dashboard mereka, bukan dengan mengunggah file .env secara langsung. Prinsipnya tetap sama seperti yang kita pelajari di artikel kedua: konfigurasi sensitif tidak boleh ikut ter-commit ke kode, baik itu lewat file .env lokal maupun repository Git.

• Pastikan platform hosting yang kamu pakai benar-benar mengeset NODE_ENV=production di environment mereka. Beberapa platform melakukan ini otomatis, tapi ada juga yang perlu diset manual — kalau lupa, kode kita di poin 3.1 akan tetap menganggapnya sebagai “bukan development” (karena kondisinya === "development", bukan !== "production") sehingga stack trace tetap tersembunyi, tapi log Environment: undefined di poin 3.2 akan jadi tanda peringatan bahwa konfigurasi belum lengkap.

4. Menambahkan Referensi README di package.json

Sebagai sentuhan terakhir, tambahkan field homepage di package.json yang mengarah ke README di repository (akan berfungsi penuh setelah project di-push ke GitHub di artikel selanjutnya):

{
  "name": "todo-api",
  "version": "1.0.0",
  "description": "Todo List API — boilerplate backend Node.js, Express, dan MongoDB",
  "homepage": "https://github.com/username-kamu/todo-api#readme",
  "main": "src/server.js"
}

Penjelasan teknis: field homepage ini dibaca oleh npm dan beberapa tools lain untuk menunjukkan “dari mana project ini bisa dipelajari lebih lanjut”. Kalau project ini nanti di-publish ke npm registry (di luar cakupan seri ini), field ini juga yang muncul di halaman package tersebut sebagai link dokumentasi.

5. Perbandingan Sebelum dan Sesudah

6. Kesimpulan

README.md yang baik adalah jembatan antara kode yang kamu tulis dan orang lain yang perlu memakainya — entah itu rekan tim, penilai magang, atau dirimu sendiri enam bulan dari sekarang yang sudah lupa detail project ini. Dengan menuliskan fitur, cara instalasi, environment variable (termasuk perbedaan NODE_ENV antara development dan production), dan referensi dokumentasi API secara jelas, project Todo List API kita sekarang benar-benar siap dibagikan ke orang lain.

Satu langkah terakhir yang tersisa: membuat project ini benar-benar bisa diakses secara online lewat GitHub, lengkap dengan riwayat perubahan kode yang rapi.

Lanjutkan ke artikel terakhir: Panduan Push Project Node.js ke GitHub: Git Init Sampai Repository Online