File netlify.toml adalah sebuah file konfigurasi berbasis format TOML (Tom's Obvious, Minimal Language) yang diletakkan pada direktori root sebuah proyek web. File ini berfungsi untuk mengontrol seluruh aspek perilaku deployment di platform Netlify, mulai dari direktori build, variabel lingkungan, aturan pengalihan URL (redirects), penulisan ulang URL (rewrites), hingga konfigurasi header HTTP keamanan secara terpusat tanpa harus melalui dashboard web Netlify.
Penggunaan file konfigurasi ini menjadi standar industri modern bagi para pengembang frontend untuk memastikan penerapan infrastruktur sebagai kode atau Infrastructure as Code. Setiap kali pembaruan kode didorong ke repositori Git seperti GitHub, GitLab, atau Bitbucket, sistem otomatis Netlify akan memindai file ini dan mengeksekusi instruksi build serta aturan perutean yang telah ditetapkan secara presisi dan konsisten di setiap lingkungan cabang.
Struktur Dasar dan Blok Utama Netlify TOML
Konfigurasi di dalam file netlify.toml dibagi menjadi beberapa bagian utama yang disebut dengan blok atau tabel. Blok paling umum yang wajib ada untuk aplikasi web modern seperti React, Vue, atau Vite adalah blok [build]. Blok ini mendefinisikan perintah yang harus dijalankan sistem saat proses kompilasi kode sumber menjadi aset statis yang siap didistribusikan ke jaringan global CDN Netlify.
Selain blok build, pengembang sering kali menyertakan blok konteks untuk membedakan perilaku antara lingkungan produksi, cabang staging, dan pengujian lokal. Penggunaan konteks ini sangat krusial untuk mencegah kesalahan konfigurasi API atau variabel lingkungan yang sensitif bocor ke lingkungan publik pengguna akhir saat proses rilis pembaruan perangkat lunak.
| Blok Konfigurasi | Fungsi Utama | Contoh Penggunaan |
|---|---|---|
[build] | Mengatur direktori publik, perintah build, dan fungsi serverless. | publish = "dist", command = "npm run build" |
[context.production] | Aturan khusus yang hanya berlaku pada branch produksi utama. | Pengaturan environment variables khusus produksi |
[[redirects]] | Mengatur aturan pengalihan URL, status HTTP, dan proteksi akses. | Mengarahkan semua route ke /index.html untuk SPA |
[[headers]] | Menambahkan HTTP headers kustom untuk keamanan dan performa. | Content-Security-Policy, Cache-Control, HSTS |
Pengaturan Build dan Perintah Kompilasi Proyek
Blok [build] adalah jantung dari file konfigurasi ini. Di dalamnya, Anda mendefinisikan tiga parameter esensial yaitu direktori tempat hasil build disimpan melalui kunci publish, perintah terminal yang dieksekusi melalui kunci command, dan direktori fungsi serverless jika Anda menggunakan fitur Netlify Functions.
Sebagai contoh, untuk aplikasi yang dibangun menggunakan kerangka kerja Vite atau React modern, direktori output biasanya diarahkan ke folder dist atau build. Pastikan perintah build yang dituliskan di dalam file ini sama persis dengan skrip yang terdaftar di dalam file package.json proyek Anda agar proses integrasi berkelanjutan tidak mengalami kegagalan saat proses kompilasi.
Aturan Redirect dan Rewrite untuk Single Page Application
Salah satu kendala paling sering dialami pengembang web modern adalah masalah halaman 404 ketika pengguna merefresh halaman selain beranda pada aplikasi berbasis Single Page Application seperti React Router atau Vue Router. File netlify.toml menyelesaikan masalah ini secara elegan melalui blok [[redirects]].
Dengan menambahkan aturan tangkap semua atau catch-all rule, setiap permintaan URL yang masuk akan dialihkan kembali ke file index.html utama agar perutean sisi klien dapat mengambil alih. Pengaturan ini dituliskan dengan mengarahkan status kode 200 pada target pengalihan, yang memberi tahu peramban bahwa halaman tetap valid meskipun URL yang diakses memiliki jalur bersarang.
Konfigurasi Keamanan HTTP Headers
Keamanan aplikasi web modern sangat bergantung pada konfigurasi header HTTP yang ketat untuk mencegah serangan seperti Cross-Site Scripting (XSS) dan Clickjacking. Melalui blok [[headers]] di dalam netlify.toml, pengembang dapat menyuntikkan kebijakan keamanan langsung ke tingkat CDN sebelum respons dikirimkan ke peramban pengguna.
Anda dapat menetapkan aturan header untuk semua file dengan menggunakan tanda bintang pada kunci for. Pengaturan populer meliputi penambahan header X-Frame-Options, X-XSS-Protection, serta pengaturan durasi singgahan atau cache control untuk aset statis seperti gambar, fon, dan bundel skrip JavaScript guna meningkatkan performa pemuatan halaman secara keseluruhan.