Instalasi dan Konfigurasi Jigsaw di Lingkungan ServBay

Ringkasan

Dokumen ini bertujuan untuk memandu Anda dalam menginstal dan mengonfigurasi generator situs statis Jigsaw di lingkungan pengembangan web lokal ServBay yang andal. ServBay menyediakan lingkungan terintegrasi untuk berbagai stack teknologi seperti PHP, Node.js, sehingga sangat memudahkan pembangunan proyek Jigsaw. Melalui ServBay, Anda dapat dengan mudah mengatur domain lokal, HTTPS, dan server web efisien untuk proyek Jigsaw Anda, sehingga bisa fokus pada pengembangan konten website.

Apa Itu Jigsaw?

Jigsaw adalah generator situs statis yang dibangun menggunakan komponen Laravel dan dikembangkan oleh Tighten. Dengan memanfaatkan kekuatan dan fleksibilitas engine template Blade Laravel, dikombinasikan dengan file Markdown, Jigsaw mampu menghasilkan website HTML statis murni. Jigsaw sangat ideal untuk membuat website dokumentasi, blog, landing page marketing, atau website apapun yang tidak memerlukan database backend maupun pemrosesan server dinamis. Keunggulan utama Jigsaw di antaranya:

• Menggunakan Tools yang Familiar: Jika Anda sudah mengenal Laravel atau template Blade, Anda akan sangat mudah menggunakan Jigsaw.
• Performa dan Keamanan: Website statis hasil build sangat cepat untuk dimuat dan aman karena tidak ada eksekusi kode di sisi server.
• Template yang Fleksibel: Pembuatan layout dan komponen kompleks sangat leluasa berkat Blade.
• Dukungan Markdown: Menulis konten menjadi mudah.

Skenario Penggunaan

Jigsaw sangat cocok untuk kebutuhan berikut:

• Website dokumentasi proyek dan API
• Blog pribadi atau website sharing teknologi
• Landing page marketing perusahaan atau produk
• Website showcase kecil
• Website performa tinggi dan keamanan bagus dengan konten relatif statis

Prasyarat

Pastikan Anda telah memenuhi hal-hal berikut sebelum memulai:

1. ServBay Sudah Terpasang dan Berjalan: Instal dan jalankan ServBay di macOS Anda. ServBay sudah menyertakan PHP, Composer, dan Node.js/npm, yang dibutuhkan untuk Jigsaw.
2. Dasar Penggunaan Terminal: Anda perlu menjalankan beberapa perintah di terminal.
3. Pemahaman Dasar Composer dan npm: Instalasi Jigsaw memerlukan Composer dan pembuatan aset frontend membutuhkan npm.

Langkah Instalasi dan Konfigurasi

Bagian ini akan menjelaskan langkah detail instalasi dan konfigurasi proyek Jigsaw menggunakan ServBay.

Langkah 1: Membuat Folder Proyek

Pertama, buka aplikasi terminal Anda, lalu masuk ke direktori root website sesuai rekomendasi ServBay, yaitu /Applications/ServBay/www, dan buat folder baru untuk proyek Jigsaw Anda.

cd /Applications/ServBay/www
mkdir servbay-jigsaw-demo
cd servbay-jigsaw-demo

Kita memberi nama folder proyek servbay-jigsaw-demo, dan semua file proyek akan ditempatkan di sini.

Langkah 2: Membuat Proyek Jigsaw dengan Composer

ServBay sudah menginstal dan menyiapkan Composer, sehingga Anda dapat menjalankan perintah composer di terminal mana pun. Jalankan perintah berikut di folder proyek yang sudah Anda buat (/Applications/ServBay/www/servbay-jigsaw-demo) untuk membangun proyek Jigsaw:

composer create-project tightenco/jigsaw .

Perintah ini akan mengunduh versi terbaru Jigsaw dan semua dependency PHP ke folder saat ini (.). Perhatikan tanda titik di akhir, ini menandakan proyek dibuat langsung di folder sekarang, bukan dalam subfolder baru bernama jigsaw.

Langkah 3: Konfigurasi Website di ServBay

Agar website Jigsaw Anda dapat diakses melalui browser, Anda perlu mengkonfigurasi situs web lokal di ServBay.

1. Buka ServBay UI: Klik dua kali ikon aplikasi ServBay atau buka dari menu bar untuk membuka panel kontrol.
2. Navigasi ke "Website": Pilih tab "Website" di sidebar sebelah kiri.
3. Tambah Website Baru: Klik tombol "+" di bagian bawah, lalu pilih "Tambah Website".
4. Isi Detail Website:
   • Nama: Masukkan nama yang mudah dikenali, misal ServBay Jigsaw Demo.
   • Domain: Masukkan nama domain yang ingin digunakan secara lokal. Disarankan memakai akhiran .servbay.demo untuk menghindari konflik, misal jigsaw-demo.servbay.demo. ServBay otomatis mengarahkan domain .servbay.demo ke lokal.
   • Jenis Situs: Pilih PHP, karena proses build Jigsaw memerlukan PHP.
   • Versi PHP: Pilih versi PHP yang telah terinstal di ServBay (direkomendasikan versi terbaru yang stabil).
   • Root Website: Ini sangat krusial. Output build statis Jigsaw secara default akan berada di folder build_local dalam proyek Anda. Pastikan root website diarahkan ke folder output ini: /Applications/ServBay/www/servbay-jigsaw-demo/build_local
5. Simpan dan Terapkan: Setelah semua data diisi, klik "Simpan". ServBay akan meminta Anda mengkonfirmasi perubahan; klik setuju dan ServBay akan mengupdate konfigurasi web server (Caddy atau Nginx) serta HTTPS secara otomatis.

Langkah 4: Instal Dependency Frontend

Proyek Jigsaw biasanya memanfaatkan npm untuk mengelola dan membuild aset frontend seperti SASS/CSS, file JavaScript, dan sebagainya. Dengan ServBay, Node.js dan npm sudah otomatis tersedia.

Di direktori proyek (/Applications/ServBay/www/servbay-jigsaw-demo), jalankan perintah berikut untuk menginstal dependency frontend:

npm install

Perintah ini akan membaca file package.json di root proyek dan mengunduh module Node.js yang diperlukan ke folder node_modules.

Langkah 5: Build Website Jigsaw

Setelah semua ketergantungan terpasang, Anda perlu menjalankan build Jigsaw untuk menghasilkan file situs statis.

Jalankan perintah berikut di direktori proyek:

./vendor/bin/jigsaw build

Perintah ini meliputi:

1. Mengolah file Markdown dan template Blade di folder source.
2. Menjalankan proses build dari webpack.mix.js (jika npm install sudah mengaktifkan Laravel Mix).
3. Menghasilkan file HTML, CSS, JS, dan aset lain ke folder build_local.

Langkah 6: Akses Website Anda

Sekarang file statis hasil build Jigsaw telah tersedia di /Applications/ServBay/www/servbay-jigsaw-demo/build_local. Karena root website sudah diarahkan ke sini di ServBay, Anda bisa langsung mengakses website via domain lokal yang telah diatur.

Buka browser Anda dan akses domain yang sudah dikonfigurasi pada Langkah 3, misalnya https://jigsaw-demo.servbay.demo. ServBay otomatis mengelola sertifikat HTTPS lokal (menggunakan ServBay User CA), dan Anda akan melihat halaman selamat datang default milik Jigsaw.

Kustomisasi dan Pengembangan

Setelah lingkungan dasar tersedia, Anda bisa mulai memodifikasi isi dan tampilan Jigsaw Anda.

Mengedit Konten dan Template

• Source code website Anda ada di folder source pada root proyek.
• Layout dan komponen HTML menggunakan template Blade, dan biasanya ada di subfolder seperti source/_layouts dan source/_partials.
• Konten halaman ditulis menggunakan Markdown, disimpan di source atau subfolder-nya (misal source/index.md, source/about.md).
• Postingan blog biasanya berada di source/_posts menggunakan format nama file YYYY-MM-DD-slug.md.

Menambah Halaman/Artikel Baru

Untuk menambahkan halaman atau postingan blog baru, cukup buat file Markdown baru di folder source atau subfolder terkait (misal source/_posts).

Misalnya, membuat file source/about.md:

---
title: "Tentang Kami"
description: "Informasi lebih lanjut tentang ServBay Jigsaw Demo"
---

# Tentang Kami

Ini adalah halaman "About" yang dibuat menggunakan Jigsaw.

Di sini Anda dapat menambahkan informasi perusahaan, tim, dan lain-lain.

Kustomisasi Style dan Script

Proyek Jigsaw biasanya menggunakan Laravel Mix (webpack.mix.js) untuk meng-compile aset frontend.

• File stylesheet (biasanya SASS/SCSS) ada di source/_assets/sass.
• File JavaScript ada di source/_assets/js.

Di folder proyek, Anda dapat menjalankan script npm berikut:

• npm run dev: Compile aset untuk mode development, biasanya dengan Source Maps, tanpa minify.
• npm run watch: Compile dan pantau perubahan file secara otomatis—sangat membantu saat proses pengembangan.
• npm run prod: Compile aset untuk mode production, dengan optimasi dan minifikasi.

Misal, setelah mengedit source/_assets/sass/main.scss, jalankan npm run dev atau npm run watch untuk membangkitkan file CSS terbaru.

Build Ulang Website

Catatan Penting: Setiap kali Anda mengubah file konten (Markdown) atau template (Blade) di folder source, Anda harus menjalankan ulang perintah build Jigsaw agar hasil perubahan dapat ter-update ke folder build_local:

./vendor/bin/jigsaw build

Jika yang diubah adalah asset frontend (SASS, JS), jalankan npm run dev atau npm run watch untuk memperbarui hasil compile. Pada kebanyakan proyek Jigsaw, perintah build juga akan otomatis mengaktifkan proses build Mix, namun pemahaman terpisah akan memudahkan proses debug.

Hal-hal Penting

• Folder Output Build: Jigsaw secara default membuild ke build_local (develop) dan build_production (production). Pastikan root website di ServBay diarahkan ke folder yang ingin diakses (biasanya build_local untuk develop).
• Web Server: ServBay menggunakan Caddy atau Nginx yang melayani file statis langsung dari build_local secara efisien. Anda tidak perlu memakai perintah jigsaw serve bawaan Jigsaw (lebih sederhana namun fiturnya tidak sekuat server ServBay).
• HTTPS: ServBay akan otomatis menyiapkan HTTPS untuk domain .servbay.demo dan menandatangani sertifikat melalui ServBay User CA. Pastikan Anda telah memercayai CA ServBay di sistem agar tidak muncul warning di browser.
• Clean Build: Jika Anda menemui masalah build aneh, coba jalankan perintah ./vendor/bin/jigsaw build --clean untuk membersihkan build lama.

FAQ (Pertanyaan Umum)

Q: Saya sudah mengubah file Markdown, tapi tampilan website di browser belum berubah?

A: Setelah mengubah konten atau template, Anda harus menjalankan perintah ./vendor/bin/jigsaw build di terminal untuk membuild ulang website.

Q: Saya sudah edit file SCSS, tapi perubahan style tidak muncul?

A: Setelah mengubah asset frontend, jalankan npm run dev atau npm run watch di folder proyek untuk meng-compile ulang asset frontend.

Q: Mengapa saat mengakses domain lokal muncul error “tidak dapat diakses” atau “file tidak ditemukan”?

A: Cek beberapa poin berikut:

1. Pastikan ServBay aktif dan berjalan.
2. Cek konfigurasi website di ServBay: apakah domain sudah benar? Apakah root website sudah diarahkan ke /Applications/ServBay/www/servbay-jigsaw-demo/build_local?
3. Pastikan Anda telah menjalankan perintah ./vendor/bin/jigsaw build, dan folder build_local sudah berisi file statis seperti index.html.

Q: Bagaimana cara deploy website Jigsaw?

A: Website hasil Jigsaw adalah file statis murni. Biasanya langkahnya:

1. Jalankan ./vendor/bin/jigsaw build production untuk membuild folder production (optimasi maksimal).
2. Upload semua file dari folder build_production ke layanan hosting statis manapun (Netlify, Vercel, GitHub Pages, layanan cloud, dll).

Kesimpulan

Dengan ServBay, proses instalasi dan konfigurasi generator situs statis Jigsaw di macOS menjadi sangat cepat dan efisien. ServBay menyediakan seluruh kebutuhan lingkungan (PHP, Composer, Node.js, npm), serta kemampuan konfigurasi server web lokal yang canggih. Ikuti langkah pada panduan ini untuk dengan mudah memulai proyek Jigsaw, lalu maksimalkan fitur ServBay untuk memperlancar alur kerja pengembangan lokal Anda.