Menyiapkan pengembangan lokal untuk Azure Static Web Apps

Saat dipublikasikan ke cloud, situs Azure Static Web Apps menautkan banyak layanan yang bekerja bersama seolah-olah mereka adalah aplikasi yang sama. Layanan ini meliputi:

• Aplikasi web statis
• Azure Functions API
• Layanan autentikasi dan otorisasi
• Layanan perutean dan konfigurasi

Layanan ini harus berkomunikasi satu sama lain, dan Azure Static Web Apps menangani integrasi ini untuk Anda di cloud.

Namun, saat Anda menjalankan aplikasi secara lokal, layanan ini tidak secara otomatis terikat bersama-sama.

Untuk memberikan pengalaman serupa dengan yang Anda dapatkan di Azure, Azure Static Web Apps CLI menyediakan layanan berikut:

• Server situs statis lokal
• Proksi ke server pengembangan kerangka kerja ujung depan
• Proxy ke titik akhir API Anda - tersedia melalui Azure Functions Core Tools
• Autentikasi tiruan dan server perizinan
• Rute lokal dan penerapan pengaturan konfigurasi

Catatan

Sering kali situs yang dibangun dengan kerangka kerja ujung depan memerlukan pengaturan konfigurasi proksi untuk menangani permintaan dengan benar di bawah rute api. Saat menggunakan Azure Static Web Apps CLI, nilai lokasi proksi adalah /api, dan tanpa CLI, nilainya adalah http://localhost:7071/api.

Cara kerjanya

Bagan berikut ini memperlihatkan bagaimana permintaan ditangani secara lokal.

Penting

http://localhost:4280 Buka untuk mengakses aplikasi yang dilayani oleh CLI.

• Permintaan yang dibuat ke 4280 port diteruskan ke server yang sesuai tergantung pada jenis permintaan.

• Permintaan konten statis, seperti HTML atau CSS, ditangani oleh server konten statis CLI internal, atau oleh server kerangka kerja ujung depan untuk penelusuran kesalahan.

• Permintaan autentikasi dan otorisasi ditangani oleh emulator, yang menyediakan profil identitas palsu ke aplikasi Anda.

• Runtime^{Functions Core Tools 1} menangani permintaan ke API situs.

• Respons dari semua layanan dikembalikan ke browser seolah-olah semuanya adalah satu aplikasi.

Setelah Anda memulai UI dan aplikasi AZURE Functions API secara independen, lalu mulai CLI Static Web Apps dan arahkan ke aplikasi yang sedang berjalan menggunakan perintah berikut:

swa start http://localhost:<DEV-SERVER-PORT-NUMBER> --api-location http://localhost:7071

Secara opsional, jika Anda menggunakan swa init perintah , Static Web Apps CLI melihat kode aplikasi Anda dan membangun file konfigurasi swa-cli.config.json untuk CLI. Saat Anda menggunakan file swa-cli.config.json , Anda dapat menjalankan swa start untuk meluncurkan aplikasi Anda secara lokal.

¹ Azure Functions Core Tools secara otomatis diinstal oleh CLI jika belum ada di sistem Anda.

Artikel berikut merinci langkah-langkah untuk menjalankan aplikasi berbasis simpul, tetapi prosesnya sama untuk bahasa atau lingkungan apa pun.

Prasyarat

• Situs Azure Static Web Apps yang ada: Jika Anda tidak memilikinya, mulailah dengan aplikasi starter vanilla-api.
• Node.js dengan npm: Jalankan versi Node.js LTS, yang mencakup akses ke npm.
• Visual Studio Code: Digunakan untuk menelusuri kesalahan aplikasi API, tetapi tidak diperlukan untuk CLI.

Mulai

Buka terminal ke folder akar situs Azure Static Web Apps Anda yang sudah ada.

1. Pasang CLI.

   npm install -D @azure/static-web-apps-cli
   

   Tip

   Jika Anda ingin menginstal SWA CLI secara global, gunakan -g sebagai ganti -D. Namun, sangat disarankan untuk menginstal SWA sebagai dependensi pengembangan.

2. Bangun aplikasi Anda jika diperlukan oleh aplikasi.

   Jalankan npm run build, atau perintah yang setara untuk proyek Anda.

3. Inisialisasi repositori untuk CLI.

   swa init
   

   Jawab pertanyaan yang diajukan oleh CLI untuk memverifikasi pengaturan konfigurasi Anda sudah benar.

4. Mulai CLI.

   swa start
   

5. http://localhost:4280 Buka untuk menampilkan aplikasi di browser.

Cara lain untuk memulai CLI

Deskripsi	Perintah	Komentar
Menyajikan folder tertentu	swa start ./<OUTPUT_FOLDER_NAME>	Ganti <OUTPUT_FOLDER_NAME> dengan nama folder output Anda.
Menggunakan server pengembangan kerangka kerja yang sedang berjalan	swa start http://localhost:3000	Perintah ini berfungsi saat Anda memiliki instans aplikasi yang berjalan di bawah port 3000. Perbarui nomor port jika konfigurasi Anda berbeda.
Memulai aplikasi Fungsi dalam folder	swa start ./<OUTPUT_FOLDER_NAME> --api-location ./api	Ganti <OUTPUT_FOLDER_NAME> dengan nama folder output Anda. Perintah ini mengharapkan API aplikasi Anda memiliki file di api folder . Perbarui nilai ini jika konfigurasi Anda berbeda.
Menggunakan aplikasi Fungsi yang sedang berjalan	swa start ./<OUTPUT_FOLDER_NAME> --api-location http://localhost:7071	Ganti <OUTPUT_FOLDER_NAME> dengan nama folder output Anda. Perintah ini mengharapkan aplikasi Azure Functions Anda tersedia melalui port 7071. Perbarui nomor port jika konfigurasi Anda berbeda.

Emulasi otorisasi dan autentikasi

Static Web Apps CLI meniru alur keamanan yang diimplementasikan di Azure. Saat pengguna masuk, Anda dapat menentukan profil identitas palsu yang dikembalikan ke aplikasi.

Misalnya, ketika Anda mencoba membuka /.auth/login/github, halaman dikembalikan yang memungkinkan Anda menentukan profil identitas.

Catatan

Emulator berfungsi dengan penyedia keamanan apa pun, bukan hanya GitHub.

Emulator menyediakan halaman yang memungkinkan Anda untuk memberikan nilai pokok klien berikut:

Nilai	Deskripsi
Username	Nama akun yang terkait dengan penyedia keamanan. Nilai ini muncul sebagai properti userDetails di pokok klien dan dihasilkan secara otomatis jika Anda tidak memberikan nilai.
ID Pengguna	Nilai yang dihasilkan secara otomatis oleh CLI.
Peran	Daftar nama peran, di mana setiap nama berada di baris baru.
Klaim	Daftar klaim pengguna, di mana setiap nama berada di baris baru.

Setelah masuk:

• Anda dapat menggunakan titik akhir /.auth/me, atau titik akhir fungsi untuk mengambil pokok klien pengguna.

• Menavigasi untuk /.auth/logout menghapus prinsipal klien dan mengeluarkan pengguna tiruan.

Awakutu

Ada dua konteks penelusuran kesalahan dalam aplikasi web statis. Yang pertama adalah untuk situs konten statis, dan yang kedua adalah untuk fungsi API. Penelusuran kesalahan lokal dapat dilakukan dengan mengizinkan Static Web Apps CLI untuk menggunakan server pengembangan untuk salah satu atau kedua konteks ini.

Langkah-langkah berikut menunjukkan skenario umum yang menggunakan server pengembangan untuk kedua konteks penelusuran kesalahan.

1. Mulai server pengembangan situs statis. Perintah ini khusus untuk kerangka kerja ujung depan yang Anda gunakan, tetapi sering dalam bentuk perintah seperti npm run build, npm start, atau npm run dev.

2. Buka folder aplikasi API di Visual Studio Code dan mulai sesi penelusuran kesalahan.

3. Mulai CLI Static Web Apps menggunakan perintah berikut.

   swa start http://localhost:<DEV-SERVER-PORT-NUMBER> --appDevserverUrl http://localhost:7071
   

   Ganti <DEV_SERVER_PORT_NUMBER> dengan nomor port server pengembang.

Cuplikan layar berikut menunjukkan terminal untuk skenario penelusuran kesalahan umum:

Situs konten statis berjalan melalui npm run dev.

Aplikasi Azure Functions API menjalankan sesi penelusuran kesalahan di Visual Studio Code.

Static Web Apps CLI diluncurkan menggunakan kedua server pengembangan.

Sekarang permintaan yang melalui 4280 port dirutekan ke server pengembangan konten statis, atau sesi penelusuran kesalahan API.

Untuk informasi selengkapnya tentang skenario penelusuran kesalahan yang berbeda, dengan panduan tentang cara mengkustomisasi port dan alamat server, lihat repositori Azure Static Web Apps CLI.

Contoh konfigurasi penelusuran kesalahan

Visual Studio Code menggunakan file untuk mengaktifkan sesi penelusuran kesalahan di editor. Jika Visual Studio Code tidak menghasilkan file launch.json untuk Anda, Anda dapat menempatkan konfigurasi berikut di .vscode/launch.json.

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Attach to Node Functions",
            "type": "node",
            "request": "attach",
            "port": 9229,
            "preLaunchTask": "func: host start"
        }
    ]
}

Langkah berikutnya

Mengonfigurasi aplikasi Anda