Panduan Integrasi Laravel + Next.js (Pengaturan Real-Land, 2025) – Beragampengetahuan

Tujuannya sederhana: membangun aplikasi aman yang menggunakan SSR atau SSG untuk SEO, cookie sesi aman CSRF, aturan CORS yang jelas, dan penerapan yang lancar ke Vercel plus Forge atau Vapour.

Terakhir, pembaca akan mempelajari cara menghubungkan rute dan pengontrol Laravel, mendapatkan kredensial dari Next.js, menangani CSRF dan sesi, dan menerapkan dengan percaya diri. Daftar pemecahan masalah singkat mencakup masalah umum 401, 419, dan CORS sehingga tim tidak mengalami kemacetan.

Tim akan belajar:

• Cara membangun titik akhir Laravel, middleware, dan sumber daya
• Cara mendapatkan kredensial dan menangani CSRF di Next.js
• Cara menyiapkan CORS dan cookie sesi untuk lingkungan lokal dan produksi
• Cara menerapkan ke Vercel dan Forge atau Vapor dan membuat rencana penerapan yang aman

Apa yang akan dibangun dan mengapa Laravel + Next.js akan berfungsi pada tahun 2025

Arsitekturnya menggunakan peran yang jelas. Laravel 12 menangani data, otentikasi, validasi, caching dan antrian. Next.js 15 menangani UI, perutean, SEO, dan streaming. Backend memperlihatkan REST API. Frontend menggunakan SSR atau SSG dan ISR (jika memungkinkan) agar halaman dinamis dapat menggunakannya.

• Tumpukan dan versi yang saat ini berfungsi dengan baik: Laravel 12, PHP 8.3 atau lebih tinggi, MySQL 8 atau Postgres 14 atau lebih tinggi, Redis untuk caching dan antrian, Next.js 15 dengan App Router, Node 18 atau lebih tinggi.
• Mengapa Memilih REST Plus Sanctum: Cookie sesi sederhana, cerita CSRF yang kuat, model mental sederhana. Ia bekerja dengan SPA, SSR dan rendering hybrid tanpa menyimpan token di Penyimpanan lokal.
• Model keamanan satu baris: Dalam produksi, cookie sesi disetel dengan SameSite=None dan Secure, CORS diizinkan untuk domain Next.js, dan token CSRF berasal dari titik akhir Sanctum.
• rencana pembangunan daerah: Laravel dan Next.js menggunakan HTTPS dalam produksi.
• perjanjian pembelian kembali: Dua metode repo menyediakan penerapan terpisah dan kepemilikan yang jelas. Monorepo menyediakan alat berbagi dan PR atom. Keduanya bekerja dengan baik.

Tumpukan dan versi yang akan digunakan

• Laravel 12, PHP 8.3+
• Next.js 15 dengan App Router, Node 18+
• MySQL 8 atau Postgres 14+, Redis untuk caching dan antrian
• Laravel Sanctum untuk otentikasi berbasis sesi
• Vite untuk aset Laravel meskipun frontendnya mandiri
• Docker bersifat opsional; ini memfasilitasi keseimbangan antar mesin dan CI

Jika tim sekarang lebih memilih untuk mempertahankan Next.js 14, alur App Router serupa dan tetap menjadi pilihan yang aman.

Tata letak proyek dan pembelian kembali

Dua tata letak sederhana berfungsi:

1. Dua perjanjian pembelian kembali
2. monorepo
   • aplikasi/laravel-backend
   • Aplikasi/Frontend Berikutnya

Aliran data dan model keamanan

• Next.js pertama-tama meminta cookie Sanctum CSRF dari Laravel.
• Next.js memposting kredensial ke titik akhir login, yang berisi kredensial.
• Laravel menetapkan cookie sesi khusus HTTP jika berhasil.
• Panggilan API berikutnya menyertakan kredensial sehingga sesi tetap aktif.
• Dalam produksi, gunakan HTTPS. Cookie harus menggunakan Secure dan SameSite=None untuk digunakan di seluruh situs.
• CORS hanya mengizinkan asal front-end. Kredensial harus diaktifkan di permintaan browser dan Laravel CORS.
• Terapkan pembatasan kecepatan untuk melindungi autentikasi dan titik akhir yang banyak membaca.

URL dan port pengembangan lokal

Tambahkan sumber ini ke CORS di Laravel dan aktifkan kredensial. Untuk HTTPS asli, mkcert dapat membantu, namun HTTP juga cocok untuk pengembangan jika cookie dan CSRF ditangani dengan hati-hati.

Siapkan Laravel 12 dengan REST API yang bersih menggunakan Sanctum

Bagian ini mencakup pengaturan praktis untuk menghindari penggunaan senjata biasa. Itu membuat kode tetap sederhana dan fokus pada apa yang dikonfigurasi dan alasannya.

Apa yang akan ditambahkan:

• Titik akhir REST berversi di bawah /api/v1
• Kiblat otentikasi berbasis sesi
• CORS dan CSRF yang disesuaikan untuk domain Next.js yang terpisah
• Default aman untuk validasi, sumber daya, dan penomoran halaman
• Menangkan performa dengan mudah menggunakan caching, pramuat, dan pembatasan kecepatan

Untuk informasi latar belakang lebih lanjut tentang SSR dan Sanctum, panduan ini selaras dengan poin inti yang dibahas dalam Mengintegrasikan Laravel Sanctum dengan Next.js SSR: Essentials.

Instalasi dan konfigurasi inti

• Buat proyek Laravel 12 baru. Setel PHP ke versi 8.3 atau lebih tinggi.
• Sanctum diperlukan, publikasikan konfigurasi sesuai kebutuhan, dan jalankan migrasi.

Perutean otentikasi dan middleware

Titik akhir minimum:

• dapatkan-suaka/csrf-cookie
• Masuk melalui surat
• daftar pos
• logout POST
• GET /api/v1/user atau /api/v1/me terletak di belakang auth:sanctum

Semua rute yang dilindungi menggunakan auth: sainttum middleware. Frontend harus mendapatkan cookie CSRF sebelum memposting ke titik akhir login atau logout. Ini menghindari kesalahan 419.

Pengontrol, validasi, dan sumber daya API

• Pengontrol diatur dalam App\Http\Controllers\API\V1.
• Gunakan kelas permintaan formulir untuk validasi. Jaga agar aturan tetap jelas dan pesannya bermanfaat.
• Standarisasi respons menggunakan sumber daya Laravel API. Hal ini menjaga payload tetap konsisten.
• Tambahkan penomoran halaman ke titik akhir daftar, dengan ukuran halaman default yang wajar.
• Mengembalikan respons kesalahan yang jelas yang berisi pesan dan kode status HTTP yang cocok dengan masalahnya.

Default keamanan dan kecepatan

• Aktifkan pembatasan tingkat pada autentikasi dan titik akhir tulis. Terapkan pembatasan berbasis pengguna atau berbasis IP yang wajar.
• Tambahkan pemuatan bersemangat untuk menghilangkan kueri N+1.
• Cache titik akhir yang banyak dibaca jika memungkinkan. Gunakan tag untuk menghapus cache ketika data berubah.
• Sanitasi dan validasi semua masukan. Hanya bidang wajib dari respons yang dikembalikan.
• Rencanakan pembuatan versi API di bawah /api/v1 sehingga perubahan di masa mendatang tidak merusak klien.

Membangun front-end Next.js 15 yang berinteraksi dengan Laravel

Next.js menggunakan App Router untuk menangani SSR dan SSG. Komponen server mengambil data di server, yang menjaga rahasia tetap aman dan mengurangi pekerjaan klien. Jika membantu, gunakan pengendali rute untuk perpipaan API sisi server.

Untuk panduan langkah demi langkah dalam memasangkan versi ini, referensi ini cocok dengan proses di sini: Cara menghubungkan Next.js 15 dengan Laravel 12.

Inisialisasi proyek dan lingkungan

• Buat aplikasi Next.js 15 baru menggunakan App Router.
• meletakkan NEXT_PUBLIC_API_URL untuk membaca dengan aman di browser bila diperlukan.
• Tetapkan pribadi API_URL Hanya untuk penggunaan server. jangan pernah mengungkapkan rahasia NEXT_PUBLIC variabel.
• Dalam kode server, process.env digunakan saat membuat permintaan pengambilan. Hindari membocorkan URL internal ke klien kecuali dilakukan dengan sengaja.

Model akuisisi data: SSR, SSG dan ISR

• SSR untuk halaman khusus pengguna atau data yang berubah dengan cepat.
• SSG cocok untuk konten yang jarang berubah.
• ISR digunakan untuk konten yang dapat disegarkan secara berkala, seperti daftar produk.
• Di App Router, komponen server digunakan terlebih dahulu untuk mendapatkan sebagian besar data. Ini menjaga token dan cookie dalam konteks server.
• Atur validasi ulang per rute untuk mengontrol waktu ISR.

Kredensial dan Cookie di Next.js

• Gunakan pengambilan yang menyertakan kredensial sehingga cookie mengalir ke dua arah.
• Urutan loginnya selalu: dapatkan cookie CSRF dari Laravel, lalu login dengan kredensial, lalu dapatkan rute yang dilindungi.
• Di pengendali rute, teruskan cookie dalam permintaan ke Laravel.
• Di middleware, periksa cookie otentikasi atau lakukan panggilan pengguna cepat dan arahkan ulang jika tidak ada.

Status UI, kesalahan, dan DX

• Gunakan loading.js tingkat ketegangan dan perutean untuk menampilkan status pemuatan.
• Tangani pengecualian menggunakan error.js dan batas bagian berbahaya.
• Jika pengambilan sisi klien diperlukan, gunakan pembantu pengambilan kecil atau perpustakaan seperti SWR. Tetap sederhana.
• Gunakan TypeScript dengan tipe normal yang cocok dengan bentuk sumber daya API.
• Tambahkan metadata judul dan deskripsi. Gunakan API metadata untuk operasi SEO per halaman.

Otentikasi ujung ke ujung menggunakan Laravel Sanctum dan Next.js

Ini adalah proses yang digunakan dalam produksi. Ia menghindari kejutan 401 dan 419 dan bekerja dengan SSR.

Proses masuk biasa

• Langkah 1:Next.js memanggil GET sainttum/csrf-cookie dan menyertakan kredensial.
• Langkah 2:Next.js menerbitkan informasi login menggunakan email, kata sandi, dan kredensial.
• Langkah 3: Laravel menyetel cookie sesi. Next.js kemudian memanggil /api/v1/user untuk mendapatkan file konfigurasi.
• Tempatkan logika ini di pengendali rute atau tindakan server. Jika memungkinkan, simpan di server untuk menghindari kebocoran cookie.

Lindungi halaman dan panggilan API

• Gunakan middleware untuk memeriksa cookie autentikasi atau melakukan panggilan pemeriksaan cepat ke /api/v1/user.
• Jika otentikasi tidak lulus, arahkan ke halaman login.
• Di server, verifikasi autentikasi sebelum merender halaman pengguna.
• Tangani 401 dengan pengalihan atau pesan eksplisit. Hindari putaran dengan memeriksa rute saat ini.

Status pengguna antara server dan klien

• Dapatkan pengguna saat ini di server untuk render pertama. Navigasi dapat ditampilkan dalam kondisi yang benar tanpa berkedip.
• Berikan hanya kolom yang diperlukan ke komponen klien. Jangan mengirimkan seluruh pengguna atau data sensitif ke browser.
• Setelah login atau logout, refresh data pengguna agar UI segera terupdate. Validasi ulang sederhana atau panggilan tindakan server berfungsi dengan baik.

Logout dan berakhirnya sesi

• Panggil POST logout di Laravel untuk menghapus sesi.
• Setelah logout, alihkan ke rute publik, biasanya halaman beranda atau halaman login.
• Dalam produksi, cookie harus digunakan di seluruh situs menggunakan Secure dan SameSite=None.
• Tangani batas waktu sesi dengan memperoleh kembali status pengguna. Jika gagal, alihkan ke login. Jaga pengalaman pengguna tetap lancar dan dapat diprediksi.

Terapkan dengan percaya diri: Vercel untuk Next.js, Forge, atau Vapor untuk Laravel

Penerapan produksi yang baik mencegah sebagian besar kesalahan penerapan pertama kali. Berhati-hatilah dalam menyetel variabel lingkungan, mencocokkan domain, dan menguji cookie melalui HTTPS.

Untuk gambaran praktis lainnya tentang trade-off pemasangan dan penerapan ini, bandingkan dengan Menghubungkan Laravel 12 dengan Next.js: Panduan Komprehensif.

Solusi dan lingkungan hosting

• Laravel dapat dijalankan di VPS atau hosting terkelola melalui Forge, atau tanpa server melalui Vapour.
• Menggunakan PHP 8.3+ (database yang dihosting) dan Redis untuk caching dan antrian.
• Next.js diterapkan ke Vercel. Pilih SSR atau statis yang sesuai.
• Tetapkan variabel lingkungan di kedua platform. Jangan membocorkan rahasia dalam paket front-end.

Domain, TLS, CORS, dan Cookie

• Kedua aplikasi menggunakan HTTPS. Tidak ada pengecualian yang dibuat dalam produksi.
• Di Laravel CORS, izinkan domain Next.js dan aktifkan kredensial.
• Untuk sesi lintas situs, setel cookie dengan Aman dan SameSite=None.
• Bergantung pada topologi Anda, atur domain cookie ke domain API atau domain dasar.
• APP_URL harus cocok dengan domain backend. NEXT_PUBLIC_API_URL atau API_URL harus cocok dengan domain API final yang digunakan oleh Next.js.

CI/CD dan kinerja

• Ketergantungan cache di CI untuk mempercepat penerapan.
• Jalankan migrasi Laravel selama penerapan dan rute panas, konfigurasi, dan cache tampilan.
• Menggunakan Redis untuk melakukan cache dan mengantri, serta menyesuaikan kebijakan penggusuran.
• Di Next.js, tambahkan ISR untuk konten yang mendapat manfaat dari cache. Tetap praktikkan validasi ulang nilai.
• Menambahkan pemantauan dan pelaporan kesalahan untuk kedua sisi. Kirim log ke tempat di mana tim akan meninjaunya setiap hari.

Pemecahan Masalah FAQ

• 401 Tidak Sah: Biasanya kredensial hilang saat mengambil, domain cookie salah, atau cookie tidak dikirim karena pengaturan CORS. Konfirmasi Kredensial: Berisi sudah diatur dan domain cocok.
• Halaman 419 telah kedaluwarsa: Cookie CSRF tidak disetel sebelum diposting ke halaman login atau logout. Selalu hubungi sainttum/csrf-cookie dengan kredensial terlebih dahulu.
• kesalahan CORS: Diizinkan asal atau header tidak cocok. Kredensial mungkin tidak diaktifkan di kedua sisi. Perbaiki string mentah, header, dan support_credentials di Laravel dan sertakan kredensial dalam permintaan.
• konten campurant: Satu aplikasi menggunakan HTTP dan aplikasi lainnya menggunakan HTTPS. Keduanya harus menggunakan HTTPS dalam produksi.
• offset waktu: Jika cookie gagal di beberapa wilayah, periksa waktu server dan zona waktu. Penyimpangan jam yang besar dapat merusak sesi dan jendela CSRF.

sebagai kesimpulan

Pengaturan ini memberikan pembagian kekhawatiran yang jelas, Proses otentikasi berbasis cookie yang amandan halaman cepat menggunakan SSR, SSG, atau ISR bila diperlukan. Jalur produksinya sederhana: Vercel untuk Next.js, Forge atau Vapor untuk Laravel, serta mengelola DB dan Redis. Daftar pendek mudah disimpan:

• Versi API Laravel 12 terletak di bawah /api/v1
• Otentikasi sesi Sanctum digunakan dengan cookie CSRF
• CORS dikunci ke domain frontend, kredensial diaktifkan
• Next.js 15 Pengambilan menggunakan kredensial dan pemeriksaan sisi server
• Perutean terlindungi sudah diterapkan dan kedua aplikasi berjalan pada HTTPS

Langkah selanjutnya: Tambahkan pengujian API, sambungkan pembuatan versi API untuk perubahan di masa mendatang, tambahkan pemantauan dan peringatan, serta rencanakan strategi caching dan antrean seiring pertumbuhan lalu lintas. Ingin pemahaman lebih dalam tentang nuansa SSR dan autentikasi? Simpan log referensi pola 401 dan 419 serta cara memperbaikinya, lalu otomatiskan pemeriksaan ini di CI.