Mengelola build dan routing Pages - Edge Security Acceleration

Pages memungkinkan Anda mengonfigurasi informasi build dengan cepat dan menyesuaikan perilaku routing untuk berbagai skenario melalui file esa.jsonc.

Build Pages dengan esa.jsonc

Buat file esa.jsonc di direktori root proyek Anda di GitHub. File .jsonc memungkinkan Anda mendefinisikan dan mengganti pengaturan default proyek guna konfigurasi yang lebih fleksibel.

Mengapa menggunakannya

Infrastructure as code: Konfigurasi Anda dikontrol versinya bersama kode Anda, sehingga setiap perubahan dapat dilacak.
Kolaborasi tim yang mudah: Semua anggota tim berbagi file konfigurasi yang sama, memastikan konsistensi antara pengembangan lokal dan Penyebaran di cloud.
Rollback yang praktis: Anda dapat melakukan rollback ke commit apa pun dan mereproduksi secara tepat lingkungan build-nya.

Prioritas konfigurasi

Pengaturan dalam file esa.jsonc memiliki prioritas lebih tinggi daripada pengaturan di Konsol:

Jika proyek Anda tidak memiliki file esa.jsonc:
- Sesuaikan opsi build pada halaman detail proyek di Konsol. Lihat Memodifikasi konfigurasi dasar di Konsol.
- Konfigurasi Konsol digunakan untuk penyebaran saat ini dan selanjutnya.
Jika proyek Anda memiliki file esa.jsonc:
- Sistem secara otomatis mendeteksi file tersebut dan menggunakannya sebagai satu-satunya sumber konfigurasi.
- Untuk mengubah konfigurasi, edit file esa.jsonc dan dorong perubahan ke repositori GitHub Anda.
- Pada halaman detail proyek di Konsol, semua pengaturan yang dikelola oleh esa.jsonc diabaikan.

Contoh konfigurasi

Tambahkan file esa.jsonc ke repositori Pages Anda di GitHub. Berikut contoh konfigurasinya:

{
  "name": "vite-react-template",
  "entry": "./src/index.js",
  "installCommand": "npm install",
  "buildCommand": "npm run build",
  "assets": {
    "directory": "./dist",
    "notFoundStrategy": "singlePageApplication"
  }
}

Parameter	Deskripsi
name	Proyek target untuk penyebaran. Jika proyek tidak ada, proyek baru akan dibuat secara otomatis dengan nama ini.
entry	Jalur file entrypoint untuk fungsi edge. Contoh: `./src/index.ts`.
installCommand	Konfigurasikan perintah instalasi kustom, seperti `npm install`. Ini akan mengganti perintah instalasi yang dikonfigurasi di Konsol. Untuk melewati langkah instalasi, atur perintah menjadi string kosong. Manajer paket yang didukung meliputi `npm`, `pnpm`, `yarn`, `cnpm`, dan `bun`.
buildCommand	Konfigurasikan perintah build kustom, seperti `npm run build`. Perintah ini akan mengganti konfigurasi perintah build di Konsol. Untuk melewati langkah build, atur perintah menjadi string kosong.
assets	Fitur hosting aset statis mendukung antarmuka depan website Anda. Konfigurasikan satu direktori aset per proyek. Objek `assets` menyediakan opsi berikut: `directory`: Direktori dalam output build yang akan disajikan sebagai aset statis. Contoh: `./public`, `./dist`, atau `./build`. `notFoundStrategy`: Menentukan aksi yang diambil ketika jalur yang diminta tidak sesuai dengan aset statis apa pun. singlePageApplication: Menyajikan file `index.html` dari direktori aset statis dengan status `200 OK`. Ideal untuk Aplikasi halaman tunggal (SPA). 404Page: Menyajikan file `404.html` dari direktori aset statis dengan status `404 Not Found`. Catatan Jika Anda mengonfigurasi skrip fungsi dan opsi `assets.notFoundStrategy` sekaligus, permintaan navigasi tidak akan menjalankan skrip tersebut. Permintaan navigasi adalah permintaan yang dipicu browser saat pengguna langsung mengakses halaman (misalnya, dengan mengetik URL atau mengklik tautan) dan diidentifikasi melalui header permintaan `Sec-Fetch-Mode: navigate`.

Routing untuk aset statis

Setelah Anda mengonfigurasi file esa.jsonc, URL permintaan diarahkan ke file dalam direktori aset statis berdasarkan kasus penggunaan berikut:

Default

Jika notFoundStrategy tidak dikonfigurasi dalam esa.jsonc, seperti:

{
  "name": "vite-react-template",
  "entry": "./src/index.js",
  "assets": {
    "directory": "./dist"
  }
}

ESA mengarahkan permintaan sesuai alur berikut:

Saat permintaan mencapai Titik kehadiran (POP), sistem memeriksa keberadaan aset statis yang sesuai. Jika ditemukan, aset tersebut disajikan. Jika tidak, proses dilanjutkan ke langkah 2.
Sistem memeriksa apakah terdapat skrip fungsi edge. Jika ada, skrip tersebut dijalankan. Jika tidak, sistem mengembalikan respons 404 Not Found.

Aplikasi halaman tunggal

Saat membangun aplikasi halaman tunggal, atur notFoundStrategy ke singlePageApplication dalam esa.jsonc, misalnya:

{
  "name": "vite-react-template",
  "entry": "./src/index.js",
  "assets": {
    "directory": "./dist",
    "notFoundStrategy": "singlePageApplication"
  }
}

ESA mengarahkan permintaan sesuai alur berikut:

Saat URL permintaan client mencapai POP, sistem memeriksa keberadaan aset statis yang sesuai. Jika ditemukan, file statis dikembalikan. Jika tidak, proses dilanjutkan ke langkah 2.
Sistem memeriksa apakah permintaan merupakan permintaan navigasi (memiliki header permintaan Sec-Fetch-Mode: navigate). Jika bukan, proses dilanjutkan ke langkah 3. Jika iya, permintaan diarahkan ke file /index.html, lalu proses dilanjutkan ke langkah a:
a. Sistem memeriksa keberadaan halaman index.html. Jika ada, konten /index.html dikembalikan dengan status 200 OK. Jika tidak, proses dilanjutkan ke langkah 3.
Sistem memeriksa apakah terdapat skrip fungsi. Jika ada, skrip tersebut dijalankan. Jika tidak, sistem mengembalikan respons 404 Not Found.

Membangun situs statis

Saat membangun situs statis, atur notFoundStrategy ke 404Page dalam esa.jsonc, misalnya:

{
  "name": "vite-react-template",
  "entry": "./src/index.js",
  "assets": {
    "directory": "./dist",
    "notFoundStrategy": "404Page"
  }
}

ESA mengarahkan permintaan sesuai alur berikut:

Saat URL permintaan client mencapai node edge, sistem memeriksa keberadaan aset statis yang sesuai. Jika ditemukan, file statis dikembalikan langsung. Jika tidak, proses dilanjutkan ke langkah 2.
Sistem memeriksa apakah permintaan merupakan permintaan navigasi (memiliki header permintaan Sec-Fetch-Mode: navigate). Jika bukan, proses dilanjutkan ke langkah 3. Jika iya, permintaan diarahkan ke file /index.html, lalu proses dilanjutkan ke langkah a:
a. Sistem memeriksa keberadaan halaman index.html. Jika ada, konten /index.html dikembalikan dengan status 200 OK. Jika tidak, proses dilanjutkan ke langkah 3.
Sistem memeriksa apakah terdapat skrip fungsi. Jika ada, skrip tersebut dijalankan. Jika tidak, sistem mengembalikan respons 404 Not Found.

Memodifikasi konfigurasi dasar di Konsol

Masuk ke Konsol ESA. Di panel navigasi kiri, pilih Edge Computing > Functions and Pages.
Pada halaman Functions and Pages, temukan fungsi yang ingin Anda kelola, lalu klik nama rutin atau kolom Actions lalu pilih View Details.
Pilih tab Basic Information dan klik Modify untuk bagian Build Information.

Ubah Build Information sesuai kebutuhan.

Parameter	Deskripsi
Root Dir	Direktori tempat perintah build dijalankan. Default: `/`. Jika Anda menggunakan `monorepo`, masukkan jalur subproyek yang akan dibuild (misalnya, `/frontend` atau `/packages/web`).
Static Asset Dir	Direktori dalam output build yang akan disajikan sebagai aset statis. Contoh: `./public`, `./dist`, atau `./build`. Pengaturan `assets.directory` dalam `esa.jsonc` memiliki prioritas lebih tinggi dan akan mengganti pengaturan ini.
Function File Path	Jalur file entrypoint untuk fungsi. Contoh: `./src/index.ts`. Pengaturan `entry` dalam `esa.jsonc` memiliki prioritas lebih tinggi dan akan mengganti pengaturan ini.
Node.js	Versi Node.js yang digunakan untuk build. Picu build baru agar perubahan diterapkan. Anda juga dapat menentukan versi mayor Node.js di bidang `engines.node` dalam file `package.json` Anda. Pengaturan dalam `package.json` memiliki prioritas lebih tinggi dan akan mengganti pengaturan ini.
Env Variables	Atur variabel lingkungan yang tersedia selama proses build. Akses melalui objek global `process.env`.