การตั้งค่า Web App Manifest

Web app manifest คือไฟล์ JSON ที่บอกให้ browser รู้ว่าควรแสดง PWA ของคุณอย่างไร — ตั้งแต่ชื่อ, icon, URL สำหรับเปิดแอป ไปจนถึง display mode เมื่อใช้ integration @astrojs/pwa (vite-plugin-pwa) คุณไม่ต้องเขียนไฟล์นั้นเอง เพียงประกาศค่าทั้งหมดใน astro.config.mjs แล้ว integration จะสร้างไฟล์ manifest และเชื่อมโยงให้อัตโนมัติ

ประกาศ manifest object ภายใน AstroPWA

ส่ง key ชื่อ manifest เข้าไปใน AstroPWA() โดยรองรับ manifest fields มาตรฐานทุกตัว:

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',
        description: 'A PWA built with Astro',
        theme_color: '#ffffff',
        background_color: '#ffffff',
        display: 'standalone',
        start_url: '/',
        icons: [
          { src: 'pwa-64x64.png',            sizes: '64x64',   type: 'image/png' },
          { src: 'pwa-192x192.png',           sizes: '192x192', type: 'image/png' },
          { src: 'pwa-512x512.png',           sizes: '512x512', type: 'image/png', purpose: 'any' },
          { src: 'maskable-icon-512x512.png', sizes: '512x512', type: 'image/png', purpose: 'maskable' },
        ],
      },
      pwaAssets: {
        image: 'public/logo.svg',
      },
    }),
  ],
});

อธิบาย properties สำคัญ:

name — ชื่อเต็มของแอป แสดงบน splash screen และ app store
short_name — ชื่อย่อสำหรับใช้เมื่อพื้นที่จำกัด เช่น ป้ายกำกับใต้ icon บน home screen
description — ประโยคสั้น ๆ อธิบายแอป บาง app store นำไปใช้แสดงผล
theme_color — สีที่ใช้แต่งแถบ address bar หรือ title bar ของ OS ให้ตรงกับแบรนด์คุณ
background_color — สีพื้นหลังของ splash screen ที่แสดงขณะแอปกำลังโหลด
display — ควบคุมว่าจะแสดง browser UI มากน้อยแค่ไหน (ดูตารางด้านล่าง)
start_url — URL ที่ OS จะเปิดเมื่อผู้ใช้เปิดแอป PWA ที่ติดตั้งไว้
icons — อาร์เรย์ของ image descriptors browser จะเลือกขนาดที่เหมาะสมที่สุด

ทำไมต้องมี icon 512 × 512 สองแบบ?

field ชื่อ purpose มีความหมายสำคัญ:

"any" — icon มาตรฐานใช้ในบริบทส่วนใหญ่ (app drawer, home screen บน iOS/macOS)
"maskable" — icon ที่ subject อยู่ใน “safe zone” เพื่อให้ Android ใช้ adaptive-icon mask (วงกลม, squircle ฯลฯ) ได้โดยไม่ตัดภาพ

การมีทั้งสองแบบทำให้ icon ของคุณดูถูกต้องบนทุก platform

ไฟล์ manifest.webmanifest ที่ integration สร้างให้

ตอน build integration จะเขียนไฟล์ manifest.webmanifest ไว้ที่ output root โดยเนื้อหาตรงกับที่คุณประกาศไว้:

{
  "name": "My Astro PWA",
  "short_name": "AstroPWA",
  "description": "A PWA built with Astro",
  "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", "purpose": "any" },
    { "src": "maskable-icon-512x512.png", "sizes": "512x512", "type": "image/png", "purpose": "maskable" }
  ]
}

นอกจากนี้ integration ยังฉีด tag <link rel="manifest" href="/manifest.webmanifest"> เข้าใน <head> ของทุกหน้าให้อัตโนมัติ — คุณไม่ต้องเพิ่มเองเลย

สร้าง icon อัตโนมัติด้วย pwaAssets

การปรับขนาด icon ให้ครบทุก dimension ด้วยมือเป็นเรื่องน่าเบื่อ option ชื่อ pwaAssets (ขับเคลื่อนโดย @vite-pwa/assets-generator) จะสร้าง icon variants ทั้งหมดจากภาพต้นฉบับเพียงรูปเดียว:

pwaAssets: {
  image: 'public/logo.svg',   // SVG หรือ PNG ความละเอียดสูง
},

แค่ชี้ไปที่ logo.svg ของคุณ แล้ว generator จะสร้าง pwa-64x64.png, pwa-192x192.png, pwa-512x512.png, maskable-icon-512x512.png และอื่น ๆ ให้ครบ ไม่ต้องปรับขนาดเอง

Display modes

field display ควบคุมว่า browser chrome จะแสดงมากน้อยแค่ไหนเมื่อเปิด PWA ในฐานะแอปที่ติดตั้งแล้ว:

`display`	พฤติกรรม
`standalone`	หน้าต่างแบบแอป ไม่มี browser UI
`minimal-ui`	แสดง browser UI น้อยที่สุด
`fullscreen`	เต็มหน้าจอ ไม่มี UI เลย
`browser`	แท็บ browser ปกติ

"standalone" เป็นตัวเลือกยอดนิยมสำหรับ PWA เพราะให้ประสบการณ์เหมือนแอป native โดยไม่มี address bar ให้เห็น

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

ตัวเลือก	Benefit	Cost
ตั้งค่า manifest ผ่าน astro.config.mjs (@vite-pwa/astro)	manifest ถูก generate อัตโนมัติตอน build sync กับ config เดียวเสมอ	ต้องเรียนรู้ option ของ plugin เฉพาะ Astro แทนที่จะเขียน JSON ตรงๆ
วาง manifest.json ไว้ใน public/ ตรงๆ	เห็นและแก้ไขไฟล์ได้ตรงๆ ไม่ผ่าน config abstraction	ต้อง sync ด้วยมือกับ build output เอง เสี่ยง manifest ไม่ตรงกับ asset จริง

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

ตั้ง scope/start_url ไม่ตรงกับ base path ที่ deploy จริง (เช่น deploy ใน subpath แต่ manifest ตั้ง start_url เป็น ”/”)
ไม่ generate icon ผ่าน plugin ทำให้ขนาด icon ไม่ครบตามที่ store/Android ต้องการ
ลืมว่า config เปลี่ยนต้อง rebuild ใหม่เสมอ ไม่ hot-reload เหมือนโค้ด component ปกติ

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

Astro documentation site เอง — ใช้ @vite-pwa/astro ตั้งค่า manifest ผ่าน config ให้ sync กับ build pipeline อัตโนมัติ

VitePress sites — ใช้แนวทาง config-driven manifest คล้ายกันทำให้ documentation หลายพันเว็บติดตั้งเป็น PWA ได้โดยไม่ต้องเขียน manifest.json เอง