manifest.json для PWA: обязательные поля, пример и генератор

manifest.json — это текстовый файл в формате JSON, в котором сайт сообщает браузеру своё название, иконки, адрес запуска, цвета и режим окна. Без манифеста сайт нельзя установить как PWA, а на iPhone он превратится в обычную закладку. Минимальный набор для установки в Chrome, Edge и Samsung Internet: название, иконки 192×192 и 512×512, start_url и display. Файл подключается одной строкой в head страницы, а собрать его можно в генераторе манифеста.

Формат описан в спецификации Web Application Manifest, а справочник по полям ведёт MDN. Ниже — как устроен файл, какие поля действительно нужны, как его подключить и чем отличается поведение на Android, компьютере и iPhone.

Что такое manifest.json и зачем он нужен

Манифест превращает сайт из набора страниц в «приложение» с собственной идентичностью. Браузер читает из него, как подписать иконку, какой адрес открыть при запуске, нужно ли прятать адресную строку и какой цвет показать на заставке. Именно манифест отвечает за то, что установленный сайт открывается в отдельном окне, а не во вкладке.

Название файла не принципиально: встречаются manifest.json и manifest.webmanifest. Важен не он, а то, что файл подключён через link rel="manifest" и отдаётся сервером как валидный JSON. Для расширения .webmanifest стандарт рекомендует тип application/manifest+json, но браузеры спокойно принимают и обычный application/json.

Минимальный манифест: что нужно для установки

По спецификации все поля манифеста необязательны, но для установки браузеры предъявляют свои требования. Для Chromium-браузеров (Google Chrome, Microsoft Edge, Samsung Internet) MDN перечисляет такой минимум (Making PWAs installable):

• name или short_name — название приложения.
• icons — среди иконок должны быть 192×192 и 512×512 пикселей.
• start_url — адрес, с которого открывается приложение.
• display и/или display_override — режим окна.
• prefer_related_applications — либо false, либо поля нет вообще.

Ещё одно условие вне манифеста: страница должна открываться по HTTPS (для разработки допустимы localhost и 127.0.0.1). Service worker для установки не обязателен — MDN прямо отмечает, что он нужен лишь для офлайн-режима. Подробнее об этом в статье Service worker: что это и как проверить офлайн-режим.

Рабочий пример manifest.json

{
  "id": "/",
  "name": "Мои задачи",
  "short_name": "Задачи",
  "description": "Список дел, который работает без интернета",
  "lang": "ru",
  "start_url": "/?source=pwa",
  "scope": "/",
  "display": "standalone",
  "orientation": "portrait",
  "background_color": "#ffffff",
  "theme_color": "#1a73e8",
  "icons": [
    { "src": "/icons/icon-192.png", "sizes": "192x192", "type": "image/png" },
    { "src": "/icons/icon-512.png", "sizes": "512x512", "type": "image/png" },
    {
      "src": "/icons/icon-maskable-512.png",
      "sizes": "512x512",
      "type": "image/png",
      "purpose": "maskable"
    }
  ]
}

Подключите файл в head каждой страницы, которую можно установить. MDN подчёркивает: если у PWA несколько страниц, ссылка на манифест должна быть на каждой.

<link rel="manifest" href="/manifest.webmanifest">
<meta name="theme-color" content="#1a73e8">
<link rel="apple-touch-icon" href="/icons/apple-touch-icon-180.png">

Основные поля манифеста

Режимы display и запасная цепочка

Если поле display не указано, используется browser — установленный сайт откроется как обычная вкладка. Режим standalone убирает адресную строку и даёт отдельное окно, fullscreen скрывает всё, включая строку состояния (удобно для игр), а minimal-ui оставляет минимальные элементы навигации. Если браузер не поддерживает выбранный режим, он перебирает цепочку fullscreen → standalone → minimal-ui → browser (MDN: display).

Поле display_override позволяет задать собственный порядок перебора режимов; значение display остаётся запасным вариантом для браузеров, которые это поле не знают.

start_url, scope и id: где чаще всего ошибаются

• start_url вне scope. Если адрес запуска не входит в область, приложение откроется не там, где вы ожидаете. Проверьте, что start_url начинается с префикса scope.
• Абсолютные пути без учёта подкаталога. Сайт в подпапке /app/ с start_url «/» будет запускаться с корня домена. Используйте пути относительно нужной папки.
• Параметры отслеживания. Добавлять к start_url метку вроде ?source=pwa допустимо, но страница должна одинаково открываться с ней и без неё.
• Смена id. Идентификатор нужен, чтобы браузер отличал приложение от других на том же домене. Если его не задать, он берётся из start_url; поменяв start_url, вы фактически создаёте новое приложение.

Манифест на iPhone: что учитывает Safari

Apple называет сайт веб-приложением «Домой», если в манифесте display равен standalone или fullscreen: тогда при запуске с иконки он открывается отдельно от Safari и появляется в переключателе приложений. Если манифеста с таким режимом нет (и нет мета-тега для веб-приложения), сайт сохраняется как закладка, которая с iOS 16.4 открывается в браузере по умолчанию (WebKit).

• Иконки из манифеста iOS поддерживает с версии 15.4. Если указаны и manifest icons, и apple-touch-icon, приоритет у apple-touch-icon.
• С iOS 16.4 поддерживаются поле id (оно синхронизирует настройки «Фокусирования» между устройствами) и push-уведомления для веб-приложений на экране «Домой».
• Если иконки нет вообще, iOS создаст монограмму из первой буквы названия.
• Пользователь может переименовать приложение при добавлении, и один сайт можно добавить на экран несколько раз.

Как добавить сайт на iPhone и что делать, если пункта нет в меню, разобрано в статьях Как добавить сайт на экран «Домой» и Нет кнопки «На экран Домой» на iPhone.

Как собрать манифест в генераторе

Как проверить манифест

1. Откройте сайт в Chrome, нажмите F12 и перейдите на вкладку «Application» → «Manifest». DevTools покажет разобранные поля, иконки и предупреждения (документация Chrome).
2. Запустите PWA-чекер или просмотр манифеста для публичного адреса: инструмент найдёт файл и покажет, что в нём не так.
3. Проверьте установку на реальном устройстве: на Android — пункт «Установить приложение» в меню Chrome, на iPhone — «Поделиться» → «На экран „Домой“».
4. Если сайт планируется упаковать в Android-приложение, пройдите проверку готовности APK.

Частые ошибки

Если вы не разработчик и хотите просто поставить готовое приложение, посмотрите каталог PWA и инструкцию Как установить PWA. Общую картину даёт статья Что такое PWA.