Setting Up @vite-pwa/astro

ติดตั้งและตั้งค่า @vite-pwa/astro

@vite-pwa/astro คือ Astro integration ที่สร้างบน Vite PWA โดยเฉพาะ ทำหน้าที่เชื่อม service worker และ web app manifest เข้ากับ build process ของ Astro โดยตรง ทำให้ได้ PWA ที่สมบูรณ์แบบโดยแทบไม่ต้องตั้งค่าด้วยตนเอง

เนื่องจาก Astro เป็น SSG framework integration นี้จะ precache ผลลัพธ์ที่ build ออกมาโดยอัตโนมัติ ทั้งหน้าเพจ script stylesheet และ asset ต่าง ๆ ทำให้ใช้งานได้แบบ offline ทันทีหลังเข้าชมครั้งแรก

การติดตั้ง

ติดตั้งแพ็กเกจด้วย package manager ที่ถนัด:

npm install -D @vite-pwa/astro
# or
pnpm add -D @vite-pwa/astro

เพิ่ม integration

เปิด astro.config.mjs แล้วเพิ่ม AstroPWA เข้าไปใน array ของ integrations:

import { defineConfig } from 'astro/config'
import AstroPWA from '@vite-pwa/astro'

export default defineConfig({
  integrations: [
    AstroPWA({
      registerType: 'autoUpdate',
      manifest: {
        name: 'My Astro PWA',
        short_name: 'AstroPWA',
        theme_color: '#ffffff',
        icons: [
          { src: 'pwa-192x192.png', sizes: '192x192', type: 'image/png' },
          { src: 'pwa-512x512.png', sizes: '512x512', type: 'image/png' },
        ],
      },
      workbox: {
        globPatterns: ['**/*.{css,js,html,svg,png,ico}'],
      },
      devOptions: {
        enabled: true,
      },
    }),
  ],
})

registerType

registerType ควบคุมวิธีที่ service worker จัดการการอัปเดตเมื่อ deploy เวอร์ชันใหม่

'autoUpdate' — service worker ติดตั้งและ activate เงียบ ๆ ในพื้นหลัง ผู้ใช้จะได้รับเวอร์ชันล่าสุดเสมอโดยไม่เห็น prompt ใด ๆ
'prompt' — service worker รอให้โค้ดของคุณยืนยันการอัปเดต ใช้ virtual:pwa-register เพื่อแสดงปุ่ม “โหลดใหม่เพื่ออัปเดต” แก่ผู้ใช้

import { registerSW } from 'virtual:pwa-register'
registerSW({ immediate: true })

นำเข้า src/pwa.ts ใน root layout เพื่อเปิดใช้งาน registration logic บนทุกหน้าเพจ

manifest option

manifest object จะถูก inject เป็น tag <link rel="manifest"> และ serve ในรูปแบบ manifest.webmanifest กรอกอย่างน้อย name, short_name, theme_color และ icons integration จะตรวจสอบความถูกต้องของ manifest ในตอน build และแจ้งเตือนหากมีฟิลด์ที่จำเป็นขาดหายไป

workbox กับ injectManifest

โดยค่าเริ่มต้น @vite-pwa/astro ใช้กลยุทธ์ workbox ซึ่งสร้าง service worker ให้อัตโนมัติ array workbox.globPatterns บอกให้ Workbox รู้ว่าไฟล์ที่ build แล้วชิ้นไหนบ้างที่ต้องเพิ่มเข้า precache manifest — ['**/*.{css,js,html,svg,png,ico}'] ครอบคลุม asset ประเภทหลักทั้งหมด

หากต้องการควบคุม service worker อย่างเต็มที่ ไม่ว่าจะเป็น routing แบบกำหนดเอง background sync หรือการจัดการ push ให้เปลี่ยนเป็นกลยุทธ์ injectManifest:

AstroPWA({
  strategies: 'injectManifest',
  srcDir: 'src',
  filename: 'sw.ts',
  manifest: { /* ... */ },
})

เมื่อใช้ injectManifest คุณเขียน src/sw.ts เอง ในตอน build Vite PWA จะ compile ไฟล์นั้นและ inject รายการ precache manifest เข้าไป ทำให้ได้ทั้งความยืดหยุ่นและการ precache อัตโนมัติพร้อมกัน

devOptions

โดยค่าเริ่มต้น service worker จะถูกปิดใน Vite dev server เนื่องจาก hot-module replacement กับ service worker ที่มีการ cache ไม่เข้ากัน ตั้งค่า devOptions.enabled: true เพื่อลงทะเบียน SW ในระหว่าง development เพื่อให้สามารถทดสอบพฤติกรรม offline และ manifest metadata ได้โดยไม่ต้อง build สำหรับ production ก่อน

AstroPWA({
  // ...other options
  devOptions: {
    enabled: true,
  },
})

ข้อแลกเปลี่ยน

ตัวเลือก	Benefit	Cost
ใช้ @vite-pwa/astro ครบชุด	ตั้งค่า service worker + manifest ให้ในคำสั่งเดียว เข้ากับ build pipeline ของ Astro ทันที	ผูกกับ ecosystem ของ Vite PWA ต้องตามอัปเดต plugin เอง
ตั้งค่า service worker เองแบบ manual ใน Astro	ไม่ผูกกับ plugin เฉพาะ ควบคุมได้เต็มที่	ต้อง integrate เข้ากับ Astro build output ด้วยมือทั้งหมด เสี่ยง bug จาก asset hash ไม่ sync

ข้อผิดพลาดที่พบบ่อย

ลืมเปิด devOptions.enabled: true ทำให้ทดสอบ service worker บน dev server ไม่ได้เลยและเข้าใจผิดว่า setup พัง
ไม่รู้ว่า Astro เป็น SSG default ทำให้ precache ทำงานเฉพาะตอน build จริง ทดสอบใน dev mode แล้วสับสนว่าทำไมไม่ cache อะไรเลย
ตั้ง registerType ผิดกับที่ต้องการ (เช่นตั้ง autoUpdate ทั้งที่อยากให้ผู้ใช้กด prompt เอง) ทำให้ UX อัปเดตไม่ตรงกับที่ออกแบบไว้

💡 ตัวอย่างจากของจริง

Vite PWA ecosystem — @vite-pwa/astro เป็นส่วนหนึ่งของ ecosystem เดียวกับที่ Elk (Mastodon client) ใช้บน Vue/React

VitePress / Astro doc sites — ใช้ setup แบบเดียวกันนี้ทำให้ documentation site ติดตั้งเป็น PWA ได้ในไม่กี่บรรทัด config