Kalau pernah menemukan folder node_modules atau cache npm ikut muncul dalam daftar perubahan Git, kemungkinan besar aturan .gitignore di project belum disiapkan dengan baik. Hal seperti ini terlihat sepele, tetapi bisa membuat repository membengkak dan proses kerja menjadi kurang nyaman.

Dalam project Node.js, sebagian besar dependency dapat dipasang kembali menggunakan package manager. Karena itu, file hasil instalasi dan cache yang sebenarnya bisa dibuat ulang tidak perlu disimpan sebagai bagian dari source code utama.

Hal yang sama berlaku untuk log, hasil coverage, file temporary, output build tertentu, serta file environment yang berisi credential. Sebaliknya, ada juga file yang tampaknya sederhana tetapi justru penting untuk dipertahankan, salah satunya lockfile.

Ilustrasi file .gitignore dengan ikon Git untuk project Node.js
.gitignore membantu Git memisahkan source code dari file hasil generate, cache, dan konfigurasi lokal.

Kenapa .gitignore Penting untuk Project Node.js?

File .gitignore memberi tahu Git file atau folder mana yang sebaiknya tidak diperhitungkan sebagai perubahan yang ingin dilacak. Aturannya berlaku berdasarkan pola nama file dan direktori sehingga kita tidak perlu menghapus file lokal hanya agar repository terlihat bersih.

Untuk Node.js, kebutuhan ini sangat terasa karena proses development menghasilkan banyak file yang bersifat sementara atau dapat dibuat ulang. node_modules/, cache package manager, log, hasil coverage, dan sebagian output build adalah contoh umum.

Intinya: .gitignore bukan alat untuk menghapus file dari komputer. Ia mengatur apa yang tidak perlu dilacak Git ketika file tersebut belum menjadi bagian dari tracking repository.

Contoh .gitignore Node.js yang Siap Dipakai

Berikut contoh konfigurasi yang mencakup dependency, cache, log, data runtime, hasil testing, output build, environment, file sistem operasi, serta konfigurasi editor. Daftar ini dapat dijadikan titik awal dan kemudian disesuaikan dengan kebutuhan project.

# =========================================
# Node.js dependencies & cache
# =========================================
node_modules/
.npm/
.npm-cache/
.pnpm-debug.log*
.yarn-cache/
.yarn-integrity
.yarnrc.yml
.pnp.*
.pnp.js
# =========================================
# Logs
# =========================================
npm-debug.log*
yarn-debug.log*
yarn-error.log*
lerna-debug.log*
# =========================================
# Runtime data
# =========================================
pids
*.pid
*.seed
*.pid.lock
# =========================================
# Coverage & testing
# =========================================
coverage/
.nyc_output/
*.lcov
# =========================================
# Build output
# =========================================
dist/
build/
.cache/
.next/
out/
.tmp/
temp/
tmp/
# =========================================
# Environment & secrets
# =========================================
.env
.env.test
.env.production
.env.local
.env.*.local
# =========================================
# OS generated files
# =========================================
.DS_Store
Thumbs.db
# =========================================
# Editor & IDE
# =========================================
.vscode/
.idea/
*.swp
*.swo
*.swn
*.swm
# =========================================
# Optional: lockfiles (pilih sesuai kebutuhan)
# =========================================
# package-lock.json
# yarn.lock
# pnpm-lock.yaml

Bagian-Bagian Penting yang Perlu Dipahami

Jangan sekadar menyalin .gitignore tanpa memahami isinya. Setiap kelompok aturan mempunyai tujuan berbeda, dan beberapa di antaranya memang harus disesuaikan dengan cara project dibangun serta dideploy.

Klik untuk melihat penjelasan setiap kelompok aturan

Dependency dan cache

node_modules/ adalah bagian paling penting untuk project Node.js. Direktori ini biasanya berisi dependency yang dipasang dari package.json dan lockfile sehingga tidak perlu disimpan satu per satu di repository.

Aturan seperti .npm-cache/, .npm/, .yarn-cache/, dan pola cache lainnya juga bertujuan mencegah data lokal hasil package manager masuk ke commit.

Log

File seperti npm-debug.log*, yarn-debug.log*, dan lerna-debug.log* biasanya hanya berisi catatan ketika terjadi masalah pada proses tooling. Log semacam ini dapat dibuat ulang dan umumnya tidak diperlukan sebagai bagian source code.

Runtime data

File dengan ekstensi seperti .pid, .seed, atau .pid.lock biasanya berhubungan dengan proses yang sedang berjalan. Data tersebut bersifat lokal atau sementara sehingga tidak cocok menjadi bagian repository source.

Coverage dan testing

Folder coverage/ dan .nyc_output/ berisi hasil pengujian atau instrumentasi. File *.lcov juga termasuk hasil yang dapat dibuat ulang ketika proses testing dijalankan.

Build output

Folder seperti dist/, build/, .next/, dan out/ dapat berisi hasil kompilasi atau proses build. Dalam banyak workflow, file tersebut dibuat ulang oleh CI/CD sehingga source code saja yang disimpan di repository.

Namun, aturan ini tidak universal. Jika repository memang digunakan untuk mem-publish hasil build secara langsung, misalnya workflow tertentu yang sengaja menyimpan output deployment di branch repository, folder tersebut mungkin justru harus dilacak.

Environment dan credential

Bagian .env perlu mendapat perhatian khusus. File environment sering digunakan untuk menyimpan API key, password, token, credential database, atau konfigurasi rahasia lainnya.

Jangan memasukkan credential asli ke repository publik. Bahkan jika sebuah file sudah dimasukkan ke .gitignore, rahasia yang sebelumnya pernah di-commit tetap dapat berada di riwayat Git dan memerlukan tindakan pembersihan tambahan.

File sistem operasi dan editor

.DS_Store dan Thumbs.db adalah contoh file yang dapat dibuat otomatis oleh sistem operasi. Sementara itu, folder seperti .vscode/ dan .idea/ dapat berisi konfigurasi lokal editor atau IDE.

Untuk konfigurasi editor, kebutuhan setiap tim berbeda. Jika suatu konfigurasi memang merupakan bagian dari standar project dan sengaja dibagikan kepada semua developer, aturan pengabaian tersebut sebaiknya ditinjau kembali.

Apakah Lockfile Harus Diabaikan?

Ini salah satu bagian yang sering membingungkan. Pada contoh di atas, package-lock.json, yarn.lock, dan pnpm-lock.yaml ditulis sebagai komentar sehingga tidak benar-benar diabaikan.

Untuk kebanyakan application atau project yang membutuhkan build reproducible, lockfile justru sebaiknya disimpan di repository. Lockfile membantu package manager menggunakan versi dependency yang sudah ditentukan sehingga hasil instalasi lebih konsisten antara komputer developer dan lingkungan CI/CD.

Praktik yang disarankan: jangan mengabaikan lockfile hanya demi mendapatkan dependency yang selalu terbaru. Jika ingin memperbarui dependency, lakukan update secara sengaja dan commit perubahan lockfile bersama perubahan project yang relevan.

Kapan lockfile mungkin tidak digunakan?

Ada workflow tertentu yang memang memiliki kebijakan berbeda, tetapi keputusan tersebut sebaiknya dibuat secara sadar oleh tim. Jangan menghapus tracking lockfile hanya karena melihatnya sebagai file tambahan yang tidak diperlukan.

Perbedaan Ignored dengan File yang Sudah Terlanjur Di-Commit

Satu hal penting yang sering mengejutkan pengguna Git adalah .gitignore tidak otomatis mengeluarkan file yang sudah terlanjur dilacak. Jika node_modules/ sebelumnya pernah di-commit, menambahkan node_modules/ ke .gitignore saja tidak selalu menyelesaikan masalah tracking.

Dalam kondisi seperti itu, file atau direktori perlu dikeluarkan dari index Git tanpa harus menghapus salinan lokalnya. Setelah itu, aturan .gitignore akan mencegahnya kembali sebagai perubahan yang perlu dilacak.

git rm -r --cached node_modules
git add .gitignore
git commit -m "chore: ignore Node.js dependencies"

Perintah tersebut bekerja pada index Git, sehingga tujuannya berbeda dengan menghapus folder dependency dari komputer. Setelah commit, Git tidak lagi melacak isi node_modules/ selama aturan pengabaiannya tetap berlaku.

Kenapa node_modules Tidak Perlu Masuk Repository?

Dependency Node.js dapat berjumlah sangat banyak karena sebuah package bisa memiliki dependency lain di bawahnya. Akibatnya, satu project kecil dapat menghasilkan ribuan file di dalam node_modules/.

Menyimpan direktori tersebut di Git bukan hanya membuat repository lebih besar. Proses clone, fetch, checkout, indexing, dan berbagai operasi Git juga dapat menjadi lebih berat.

Source dependency biasanya dapat diperoleh kembali melalui package manager. Yang lebih penting untuk repository adalah deklarasi dependency serta mekanisme yang memastikan versi yang dibutuhkan dapat direproduksi.

Jangan Mengandalkan .gitignore untuk Menyembunyikan Rahasia

.gitignore memang penting untuk mencegah file environment masuk commit secara tidak sengaja, tetapi ia bukan sistem keamanan untuk credential yang sudah terlanjur tersebar.

Jika API key atau password pernah masuk ke repository, menghapus file pada commit terbaru tidak otomatis menghapusnya dari seluruh sejarah Git. Credential tersebut sebaiknya dianggap telah terekspos dan segera diganti atau dicabut sesuai sistem yang digunakan.

Kebiasaan aman untuk file environment:
  • Simpan credential lokal di file environment yang diabaikan Git.
  • Gunakan contoh konfigurasi seperti .env.example tanpa credential asli jika project membutuhkannya.
  • Simpan secret production melalui mekanisme secret management atau environment variables pada platform deployment.
  • Jangan menaruh password, API key, token, atau credential database asli di source code.

Apakah Semua Isi Contoh Harus Dipakai?

Tidak. .gitignore yang baik bukan yang paling panjang, tetapi yang sesuai dengan struktur project dan workflow. Project Node.js sederhana, aplikasi Next.js, package library, monorepo, dan project yang menghasilkan build untuk deployment dapat membutuhkan aturan berbeda.

Contoh di atas sengaja dibuat cukup luas agar dapat menjadi dasar. Setelah itu, periksa folder project dan tentukan mana yang benar-benar merupakan source code, konfigurasi bersama, dependency hasil instalasi, cache, output build, serta file lokal.

Klik untuk checklist sebelum commit pertama
  • Pastikan node_modules/ tidak masuk daftar file yang akan di-commit.
  • Pastikan cache npm, Yarn, atau package manager lain tidak ikut repository.
  • Periksa file log dan hasil testing yang sifatnya dapat dibuat ulang.
  • Tentukan apakah folder build memang perlu disimpan atau dibuat oleh CI/CD.
  • Pastikan file .env dan file environment lokal tidak berisi credential yang akan dipublikasikan.
  • Periksa lockfile dan jangan mengabaikannya tanpa alasan yang jelas.
  • Evaluasi aturan .vscode/ atau .idea/ jika tim memang menggunakan konfigurasi editor bersama.
  • Gunakan git status sebelum commit untuk melihat apa saja yang benar-benar akan masuk repository.

Repository Bersih Dimulai dari Aturan yang Sederhana

.gitignore memang hanya sebuah file teks, tetapi dampaknya cukup besar terhadap kualitas repository. Aturan yang tepat membuat Git fokus menyimpan source code dan konfigurasi yang memang diperlukan, bukan berbagai file sementara yang muncul selama development.

Untuk project Node.js, titik awal yang paling penting adalah mengabaikan node_modules/, cache, log, hasil coverage, file temporary, serta environment lokal yang berisi rahasia. Setelah itu, sesuaikan aturan build dan konfigurasi editor dengan workflow project.

Yang tidak kalah penting, jangan menganggap semua file yang terlihat seperti “hasil generate” harus diabaikan. Lockfile, konfigurasi project, atau output tertentu bisa saja merupakan bagian penting dari proses build. Kuncinya adalah memahami apakah file tersebut merupakan source yang perlu direproduksi, konfigurasi yang perlu dibagikan, atau artefak lokal yang memang bisa dibuat ulang.

Dengan pendekatan seperti ini, repository tetap ringan, proses kolaborasi lebih rapi, dan risiko file cache, credential, atau konfigurasi lokal ikut tersebar dapat dikurangi sejak awal.