What a manifest.json file does and why you need one

A manifest.json file tells a browser how to display your web app when someone installs it on their phone or desktop. It holds the app's name, icon, colors, and starting page — the same way a native app has metadata. Without it, your web app can still work in a browser, but it cannot be installed as a standalone app, and users will see a generic icon instead of your branding.

The file is a single JSON document that lives in your project's root directory or in a folder you specify. When a user adds your app to their home screen (on Android) or uses "Install" from the browser menu (on desktop), the browser reads this file to know what to show them.

Key Takeaways

  • A manifest.json file is a plain text JSON document that sits in your project root or a folder you designate, and tells the browser how to display your web app when installed.
  • The file must include at least a name, short_name, icons array with at least one icon, and a start_url pointing to your app's entry page.
  • You link the manifest to your HTML by adding a single line in the <head> tag: <link rel="manifest" href="/manifest.json">
  • Icons should be PNG files in multiple sizes (at least 192x192 and 512x512 pixels) so the browser can pick the right one for each context.
  • The display property controls whether your app looks like a full-screen native app, a browser window, or something in between.

The minimum fields your manifest needs

A working manifest.json requires only a few fields. The browser will use defaults for anything you leave out, but those defaults are rarely what you want. Here are the fields that matter most:

name is the full name of your app — what appears in installation prompts and app lists. Keep it under 45 characters if you want it to display without truncation on most devices. short_name is a fallback for spaces where the full name does not fit, usually 12 characters or less. start_url is the page the browser should load when someone opens your installed app — typically "/" or "/index.html". icons is an array of image objects, each with a src (the file path), sizes (width and height in pixels), and type (usually "image/png").

The display property controls how the app looks when opened. "standalone" removes the browser address bar and looks like a native app. "fullscreen" hides even the status bar on mobile. "minimal-ui" keeps some browser controls. "browser" opens in a normal browser tab. Most projects use "standalone".

Step-by-step: writing your first manifest.json

Create a new file named manifest.json in your project root (the same folder as your index.html). Open it in any text editor — VS Code, Sublime, Notepad, anything that saves plain text.

Start with the opening brace and add the required fields:

{ "name": "My Weather App", "short_name": "Weather", "start_url": "/", "display": "standalone", "background_color": "#ffffff", "theme_color": "#2196F3", "icons": [ { "src": "/images/icon-192.png", "sizes": "192x192", "type": "image/png" }, { "src": "/images/icon-512.png", "sizes": "512x512", "type": "image/png" } ] }

Replace "My Weather App" with your actual app name, and update the icon paths to match where you store your images. The sizes field must match the actual pixel dimensions of each image — if you say "192x192" but the file is 180x180, some browsers will reject it.

Linking the manifest to your HTML

The manifest file does nothing until your HTML points to it. Open your index.html (or whatever page loads first) and add this line inside the <head> tag:

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

If your manifest.json is in a subfolder — say, a "public" folder — change the href to match: href="/public/manifest.json". The path is relative to your site's root, not to the HTML file itself.

Save the file, then open your app in a browser and check the developer tools. Go to the Application tab (Chrome, Edge) or Storage tab (Firefox), find Manifest, and click it. If the file loaded correctly, you will see all your fields listed. If you see an error, check that the path in the href matches the actual file location.

Preparing icons in the right sizes

Icons are the most common source of problems. You need at least two sizes: 192x192 pixels (for home screen shortcuts on Android) and 512x512 pixels (for splash screens and larger displays). Many developers also include 144x144 and 256x256 for better coverage, but those two are the minimum.

Create your icon as a square PNG file with a transparent background if possible. Use an image editor like Photoshop, GIMP, or even free tools like Canva or Pixlr to resize it to each required dimension. Save each version with a clear name: icon-192.png, icon-512.png, and so on. Put them all in a folder like /images or /assets, then reference that folder in your manifest.

The icon should be recognizable at small sizes — avoid thin lines or tiny text. Test by viewing the file at actual size in your browser: right-click the image, open it in a new tab, and zoom to 100% to see how it really looks.

Optional fields that improve the user experience

background_color is the color shown while your app is loading. Set it to match your app's main background so the transition feels smooth. Use a hex color like "#ffffff" for white or "#2196F3" for blue. theme_color is the color of the browser's address bar and status bar on Android — usually your app's primary brand color.

description is a short explanation of what your app does, shown in some app stores and installation prompts. Keep it under 80 characters. categories is an array of categories like ["productivity"] or ["games", "entertainment"] — useful if your app appears in app stores. screenshots is an array of images shown during installation on some devices, with src, sizes, and type fields like icons.

orientation locks the app to portrait or landscape mode on mobile. Set it to "portrait-primary" to prevent rotation, or leave it out to allow both. scope defines which URLs belong to your app — anything outside this scope opens in the browser instead. The default is the folder containing your manifest, which is usually correct.

Testing your manifest in a browser

Open your app in Chrome or Edge on a desktop computer. Click the menu (three dots), then "Install [App Name]" or "Create shortcut". If you do not see this option, the manifest has an error — check the developer tools Application tab for the exact message.

On Android, open your app in Chrome, tap the menu, and select "Install app" or "Add to Home screen". The browser will read your manifest and show your app name and icon in the installation prompt. If it shows a generic icon or the wrong name, double-check that your manifest.json is valid JSON (no missing commas or quotes) and that the icon paths are correct.

On desktop, the installed app will appear in your applications menu and taskbar. On mobile, it will sit on your home screen like any other app. Tap it to open — the browser should load your start_url without showing the address bar, because you set display to "standalone".

Frequently Asked Questions

What if my manifest.json has a syntax error?

The browser will refuse to load it and your app cannot be installed. Open the file in a JSON validator (search "JSON validator" online) and paste your entire manifest. It will highlight the exact line with the problem — usually a missing comma, a quote, or a trailing comma after the last item in an array.

Can I use SVG files for icons instead of PNG?

Some browsers support SVG in the icons array if you set the type to "image/svg+xml", but support is inconsistent. PNG is safer and more widely supported. If you want to use SVG, test it in your target browsers first.

Do I need a manifest.json to run a web app?

No. Your app will work fine in a browser without one. The manifest only enables installation as a standalone app and lets you control how it looks when installed. If you do not need that, you can skip it.

What happens if I change the manifest after someone installs my app?

The browser re-reads the manifest each time the app updates, so changes take effect on the next launch. Users do not have to reinstall. If you change the start_url or icons, those updates appear automatically.

How do I know if my manifest is working on real devices?

Deploy your app to a live server (not localhost) and open it on an Android phone or tablet in Chrome. If the install prompt appears and shows your icon and name, the manifest is working. On desktop, the install option in the browser menu is the test.