Manifest และ Icons

option manifest

แทนที่จะใช้ไฟล์ manifest.json แยกต่างหาก vite-plugin-pwa ให้คุณกำหนด manifest โดยตรงใน vite.config.ts ได้เลย plugin จะ inject manifest เข้าไปทุกหน้า HTML และเพิ่ม tag <link rel="manifest"> ให้อัตโนมัติ วิธีนี้ทำให้การตั้งค่า PWA อยู่ในที่เดียวกันกับส่วนที่เหลือของ Vite setup

กำหนด manifest ใน vite.config.ts

import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import { VitePWA } from 'vite-plugin-pwa';

export default defineConfig({
  plugins: [
    react(),
    VitePWA({
      registerType: 'prompt',
      includeAssets: ['favicon.ico', 'apple-touch-icon.png', 'robots.txt'],
      manifest: {
        name: 'My PWA App',
        short_name: 'MyApp',
        description: 'A Progressive Web App built with Vite and React',
        theme_color: '#ffffff',
        background_color: '#ffffff',
        display: 'standalone',
        start_url: '/',
        icons: [
          {
            src: 'pwa-192x192.png',
            sizes: '192x192',
            type: 'image/png',
          },
          {
            src: 'pwa-512x512.png',
            sizes: '512x512',
            type: 'image/png',
          },
          {
            src: 'pwa-512x512.png',
            sizes: '512x512',
            type: 'image/png',
            purpose: 'maskable',
          },
        ],
      },
    }),
  ],
});

includeAssets

option includeAssets บอก Workbox ให้ precache ไฟล์ static ที่ไม่ได้อยู่ใน build output โดยอัตโนมัติ ถ้าไม่ตั้งค่านี้ ไฟล์อย่าง favicon.ico และ apple-touch-icon.png ที่คุณวางไว้ใน public/ ด้วยตนเองจะไม่ถูกรวมใน precache manifest ของ service worker

includeAssets: ['favicon.ico', 'apple-touch-icon.png', 'robots.txt'],

การเพิ่มไฟล์เหล่านี้ที่นี่จะทำให้ไฟล์ถูก cache ตั้งแต่การติดตั้ง service worker ครั้งแรก ทำให้ browser และ iOS home screen เสิร์ฟไฟล์เหล่านั้นจาก cache ได้แม้ผู้ใช้จะออฟไลน์

สร้าง icon ด้วย @vite-pwa/assets-generator

แทนที่จะ export ทุกขนาด icon จาก design tool ด้วยตนเอง คุณสามารถสร้างขนาดที่ต้องการทั้งหมดจากไฟล์ SVG ไฟล์เดียวโดยใช้ package @vite-pwa/assets-generator

npx @vite-pwa/assets-generator --preset minimal logo.svg

คำสั่งนี้จะอ่าน logo.svg จาก directory ปัจจุบันและเขียน PNG icon ที่สร้างขึ้นทั้งหมดลงใน public/ preset minimal จะสร้างขนาดที่ครอบคลุม icons array ตามที่แสดงไว้ข้างต้น

apple-touch-icon และ favicon

ไฟล์ apple-touch-icon.png ขนาด 180x180 ต้องวางไว้ใน public/ เพื่อให้ Vite คัดลอกไปยัง dist/ ระหว่าง build iOS ใช้ภาพนี้เมื่อผู้ใช้เพิ่มแอปของคุณไปยัง home screen อย่าลืมใส่ไว้ใน includeAssets เพื่อให้ Workbox precache ด้วย

ไฟล์ favicon.ico ใช้กฎเดียวกัน — วางไว้ใน public/ และควรระบุไว้ใน includeAssets

ตารางอ้างอิงขนาด icon

ขนาด icon	วัตถุประสงค์
192x192	หน้าจอ Home บน Android มาตรฐาน
512x512	Splash screen / หน้าต่าง install prompt
512x512 maskable	Adaptive icon บน Android
180x180	Apple Touch Icon (หน้าจอ Home ของ iOS)

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

ตัวเลือก	Benefit	Cost
กำหนด manifest ผ่าน config ของ vite-plugin-pwa	generate icon หลายขนาดอัตโนมัติ ไม่ต้อง maintain ไฟล์ manifest.json เอง	ผูกกับ config syntax เฉพาะของ plugin ต้องเรียนรู้ option เพิ่ม
เขียน manifest.json เองแบบ static	ควบคุมได้ตรงๆ ไม่ผ่าน abstraction ของ plugin	ต้อง maintain icon หลายขนาดและ sync กับ build เองทั้งหมด

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

ใส่ icon แค่ขนาดเดียวใน config ทำให้ plugin generate ชุด icon ไม่ครบตามที่ Android/iOS ต้องการ
ลืมตั้ง base path ให้ตรงกับที่ deploy จริง ทำให้ path ของ icon ใน manifest ผิดตอน production build
ไม่ generate maskable icon แยก ทำให้ icon โดน crop เพี้ยนบน Android เหมือนไม่ได้ตั้งค่าอะไรเลย

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

Vite PWA ecosystem — โปรเจกต์อย่าง Elk (Mastodon client) ใช้ vite-plugin-pwa generate manifest และ icon ชุดเต็มอัตโนมัติจาก config เดียว

VitePress sites หลายเจ้า — ใช้ plugin เดียวกันนี้ทำให้ documentation site ติดตั้งเป็น PWA ได้โดยแทบไม่ต้องเขียน manifest เอง