PWAに必要なmanifest.jsonの基本｜iPhoneとAndroidで効く項目を実験ベースで解説

PWAを作るときに、まず出てくるのがmanifest.jsonです。

名前だけ見ると少し難しそうですが、役割はかなりシンプルです。

manifest.jsonは、そのWebページをホーム画面に追加したときの名前・アイコン・起動URL・表示方法をブラウザに伝える設定ファイルです。

PWA LABでいろいろ試していて分かったのは、manifest.jsonは全部の項目を完璧に書くより、まず必要な項目を正しく書く方が大事ということです。

特にiPhoneとAndroidでは、効く項目や見え方が違います。

この記事では、PWAに必要なmanifest.jsonの基本と、iPhone・Androidで実際に意味があった項目を整理します。

manifest.jsonとは何か

manifest.jsonは、Webアプリの設定ファイルです。

普通のWebページは、ブラウザで開くだけならHTML、CSS、JavaScriptがあれば表示できます。

でも、ホーム画面に追加してアプリのように使う場合は、ブラウザに追加情報を渡す必要があります。

たとえば、次のような情報です。

• ホーム画面に表示する名前
• ホーム画面に表示するアイコン
• アイコンから起動したときに開くURL
• ブラウザ表示にするか、アプリ風表示にするか
• アプリとして扱うURLの範囲
• スプラッシュ画面やツールバーに使う色

これらをまとめて書くのがmanifest.jsonです。

まずはこの形で十分

最小構成に近いmanifest.jsonは、次のような形です。

{
 "name": "Sample PWA",
 "short_name": "Sample",
 "start_url": ".",
 "scope": "/",
 "display": "standalone",
 "background_color": "#ffffff",
 "theme_color": "#ffffff",
 "icons": [
 {
 "src": "/icon-512.png",
 "sizes": "512x512",
 "type": "image/png",
 "purpose": "any"
 },
 {
 "src": "/icon-512-maskable.png",
 "sizes": "512x512",
 "type": "image/png",
 "purpose": "maskable"
 }
 ]
}

最初はこれくらいで十分です。

むしろ、よく分からない項目を大量に入れるより、この基本セットを正しく動かす方が大事です。

PWAは、1文字のパスミスやアイコン指定のズレだけで、普通にインストール候補から外れたり、変なアイコンになったりします。

HTMLからmanifest.jsonを読み込む

manifest.jsonは、HTMLのhead内で読み込みます。

<link rel="manifest" href="/manifest.json">

PWA LABでは、manifestの読み込みパスを間違えてハマりました。

/lab/manifest.jsonと書くべきところを、/leb/manifest.jsonにしていたことがあります。

たった1文字ですが、これだけでmanifestは読み込まれません。

ページ自体は普通に表示されるので、最初は気づきにくいです。

PWAでうまくいかないときは、まずmanifest.jsonが本当に読まれているかを確認した方がいいです。

name と short_name

nameは、Webアプリの正式な名前です。

short_nameは、ホーム画面など狭い場所で使われる短い名前です。

{
 "name": "OJapp PWA LAB",
 "short_name": "PWA LAB"
}

Androidでは、nameがスプラッシュ画面などに使われることがあります。

iPhoneでは、short_nameがホーム画面に表示される名前として意味を持ちます。

ホーム画面の名前は長すぎると省略されます。

なので、短くて分かりやすい名前をshort_nameに入れておくのが大事です。

start_url

start_urlは、ホーム画面のアイコンから起動したときに開くURLです。

{
 "start_url": "."
}

PWA LABで試していて、特別な理由がないならstart_url: "."はかなり扱いやすいと感じました。

固定で"/"や"/app/"にすると、ユーザーが別ページをホーム画面に追加したつもりでも、起動時にトップへ戻されることがあります。

もちろん、必ずトップやダッシュボードから始めたいアプリなら固定URLで問題ありません。

ただ、OJappやPetalのように「今見ているページを入口にする」設計では、start_urlを固定しすぎると体験がズレます。

iPhoneでもAndroidでも、起動URLの考え方はかなり重要です。

scope

scopeは、そのPWAがアプリとして扱われるURL範囲を決める項目です。

{
 "scope": "/lab/"
}

例えばscope: "/lab/"なら、/lab/配下のページはアプリ内として扱われます。

そこから外に出ると、ブラウザ扱いに近い表示になることがあります。

iOSでもscopeは意味があります。

scope外へ移動するとSafariのミニUIが出るような挙動が確認できています。

つまり、iPhoneでもscopeは無視されているわけではありません。

アプリ範囲を広く取りたいならscope: "/"。

特定のツールだけをPWA扱いにしたいならscope: "/tool/"のように小さくする。

この設計はかなり大事です。

display

displayは、PWAをどんな表示モードで開くかを指定する項目です。

{
 "display": "standalone"
}

基本はstandaloneでいいです。

Androidでは、standaloneにするとアプリらしい表示になります。

iPhoneでも、ホーム画面から開いたときにアドレスバーなしのアプリ風表示にできます。

PWA LABではfullscreenやminimal-uiも試しましたが、iPhoneでは大きな見た目の変化はほぼありませんでした。

Androidではfullscreenがかなり効きますが、一般的なPWAならまずはstandaloneが一番実用的です。

注意点として、display: "browser"にすると、PWAとしてのアプリ風表示が弱くなる、またはインストール候補から外れることがあります。

迷ったらstandaloneです。

background_color と theme_color

background_colorは、主に起動時の背景色やスプラッシュ画面に関係します。

theme_colorは、Android Chromeなどでツールバー色に反映されることがあります。

{
 "background_color": "#ffffff",
 "theme_color": "#ffffff"
}

Androidでは、この2つは見た目にかなり影響します。

特にtheme_colorは、PWAを開いたときの上部バーの色に反映されることがあります。

一方で、iPhoneではAndroidほど素直には反映されません。

それでもAndroid対応を考えるなら、入れておいた方がいい項目です。

icons

iconsは、ホーム画面に表示されるアイコンを指定する項目です。

{
 "icons": [
 {
 "src": "/icon-512.png",
 "sizes": "512x512",
 "type": "image/png",
 "purpose": "any"
 }
 ]
}

最低でも512×512のPNGを用意しておくと扱いやすいです。

Androidではmanifestのiconsがかなり重要です。

iPhoneでもmanifestのiconsが使われる場合があります。

ただし、iPhoneではHTML側のapple-touch-iconが優先されることがあります。

<link rel="apple-touch-icon" href="/icon-512.png">

固定アイコンのWebアプリなら、iPhone用にapple-touch-iconを入れるのは有効です。

一方で、ページごと・人ごとに違うアイコンを出したいサービスでは、固定のapple-touch-iconが邪魔になることもあります。

PetalやOJappのように、個別URLごとにアイコンを変えたい場合はここに注意が必要です。

Androidではmaskableアイコンも考える

Android向けには、maskableアイコンも考えた方がいいです。

Androidのホーム画面アイコンは、端末やランチャーによって丸や角丸などに切り抜かれます。

そのため、重要な部分が端に寄っていると、アイコンが切れて見えることがあります。

おすすめは、通常アイコンとmaskableアイコンを分ける形です。

{
 "icons": [
 {
 "src": "/icon-512.png",
 "sizes": "512x512",
 "type": "image/png",
 "purpose": "any"
 },
 {
 "src": "/icon-512-maskable.png",
 "sizes": "512x512",
 "type": "image/png",
 "purpose": "maskable"
 }
 ]
}

anyは通常アイコン用。

maskableはAndroidで切り抜かれる前提のアイコン用。

1枚のany maskableで済ませる方法もありますが、見た目まできれいにしたいなら2枚に分けた方が安全です。

iPhoneで必要なmanifest項目はこれくらい

iPhone向けだけを考えるなら、manifest.jsonで特に意識したいのは次の項目です。

• short_name：ホーム画面の名前
• start_url：起動時のURL
• scope：アプリ扱いの範囲
• display: "standalone"：アプリ風表示
• icons：ホーム画面アイコン候補

さらに、iPhone用の固定アイコンを使うならHTML側にapple-touch-iconを入れます。

<link rel="apple-touch-icon" href="/icon-512.png">

iPhoneではtheme_colorやorientationなどがAndroidほど強く効くわけではありません。

なので、iPhone向けはまず「名前・起動URL・scope・standalone・アイコン」を整えるのが現実的です。

Android Chromeでインストール候補にしたい場合

Android ChromeでPWAとしてインストール候補に乗せたいなら、manifest.jsonだけでなく、サイト全体の条件も見られます。

最低限、次のあたりを整えます。

• HTTPSで配信する
• manifest.jsonを正しく読み込む
• nameまたはshort_nameを設定する
• start_urlを設定する
• displayをstandalone以上にする
• 十分なサイズのアイコンを用意する
• Service Workerを登録する

PWA LABでは、manifest.json、Service Worker、icons、display、start_urlを整えた状態で、Chrome側のインストール判定を確認しました。

Chromeではbeforeinstallpromptが発生すると、インストール候補として扱われていることが分かります。

ただし、ChromeはmanifestやService Workerのキャッシュが強く残ることがあります。

設定を直してもすぐ反映されない場合があるので、テスト時は再読み込み、キャッシュ削除、再インストールも必要です。

Service Workerはmanifestとは別

ここは混同しやすいところです。

manifest.jsonは、ホーム画面に追加したときの名前、アイコン、起動URL、表示モードなどをブラウザに伝える設定ファイルです。

一方で、Service Workerは、キャッシュやオフライン対応に関わるJavaScriptです。

つまり、この2つは役割が違います。

• manifest.json：PWAの見た目や起動情報を伝える
• Service Worker：キャッシュやオフライン動作を制御する

ここで大事なのは、PWAとしてホーム画面に追加したり、Chromeでインストール候補に表示させたりするだけなら、Service Workerが必ず必要とは限らないという点です。

実際にPWA LABで検証しても、manifest.jsonが正しく設定されていれば、sw.jsなしでもChromeでインストール表示が出ます。

つまり、最初の段階では「manifest.jsonを正しく書くこと」がかなり重要です。

ただし、オフライン対応までしたい場合は話が変わります。

通信がない状態でもページを開きたい、CSSやJavaScriptをキャッシュしたい、アプリのように安定して動かしたい場合は、Service Workerが必要になります。

さらに、Service Workerを登録しただけでオフライン対応が完成するわけでもありません。

fetch処理やキャッシュ戦略を書いていなければ、Service WorkerがACTIVEになっていても、オフラインでは期待通りに動かないことがあります。

なので、まずはこう分けて考えると分かりやすいです。

• ホーム画面追加・インストール表示を整える → manifest.json
• オフライン対応・キャッシュ制御をする → Service Worker

Service Workerについては、別記事で詳しく解説します。

よくあるミス

manifest.jsonまわりでよくあるミスは次の通りです。

• manifestのパスが間違っている
• JSONのカンマが壊れている
• MIME typeが正しくない
• アイコンのパスが間違っている
• アイコンサイズが不足している
• displayがbrowserになっている
• start_urlが意図しないページになっている
• scopeが狭すぎる
• 古いmanifestがキャッシュに残っている

特にmanifestは、壊れていてもページ自体は表示されます。

だから気づきにくいです。

「サイトは見えているのにPWAにならない」というときは、manifest.jsonの読み込みを最初に確認してください。

関連記事

PWAの全体像を先に知りたい場合は、PWAとは？スマホのWebサイトを“アプリ化”する仕組みをわかりやすく解説が参考になります。

Service Workerやホーム画面対応を含めた作り方は、PWAの作り方｜manifest.json・Service Worker・ホーム画面対応を丁寧に解説でまとめています。

iPhoneでPWAがどこまで使えるかは、PWA×iOSでできること完全まとめ【2026年版】もあわせて読むと分かりやすいです。

まとめ

manifest.jsonは、PWAの名前、アイコン、起動URL、表示方法をブラウザに伝えるための設定ファイルです。

最初に押さえるべき項目は、name、short_name、start_url、scope、display、iconsです。

iPhoneでは、特にshort_name、start_url、scope、standalone、アイコン指定が重要です。

Android Chromeでは、manifestに加えてService WorkerやHTTPSも含めて、PWAとしての条件を整える必要があります。

全部の項目を暗記する必要はありません。

まずは必要最低限のmanifestを書いて、実機でホーム画面に追加し、Chromeでインストール判定を確認する。

これが一番早いです。