How to Create a Manifest.json File for Your Web App

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 name, icon, colors, and the URL to load when the app starts. Without it, your web app cannot be installed — browsers need this file to know what they are installing and how it should look.

The manifest is a plain text file written in JSON format (JavaScript Object Notation). You place it in your project folder, link it from your HTML, and the browser reads it during installation. It is required for Progressive Web Apps (PWAs) and makes your site installable on Android, Windows, macOS, iOS, and ChromeOS.

Key Takeaways

A manifest.json file must live in your project root or a folder you specify, and your HTML must link to it with a tag in the .
The file requires at minimum a name, short_name, icons array, start_url, and display mode — everything else is optional.
Icons must be PNG files in at least two sizes (192x192 and 512x512 pixels) so the browser can pick the right one for each device.
You can test your manifest in Chrome DevTools by opening the process tab, selecting Manifest, and checking for errors or warnings.
The manifest controls the app's theme color, background color, orientation, and whether it shows the browser address bar when installed.

Create the manifest.json file and add required fields

Start by creating a new file called manifest.json in your project root (the same folder as your index.html). Open it in your code editor and add the required fields as a JSON object. The browser will not install your app without at least name, short_name, icons, start_url, and display.

Here is a working example:

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

The name field is the full app name shown during installation. The short_name is what appears on the home screen or app drawer when space is tight (keep it under 12 characters). The start_url is the page the app opens to — usually "/" for your home page. The display field controls the interface: "standalone" hides the browser toolbar, "fullscreen" removes all UI, and "browser" opens it like a normal tab.

Prepare and reference your app icons

Icons are the most common source of manifest errors. You need at least two PNG files: one at 192x192 pixels and one at 512x512 pixels. The 192-pixel icon is used on home screens and app lists. The 512-pixel icon is used for splash screens and install prompts. Save both files in a folder (like /images/) and reference them by their exact path in the icons array.

Make sure the paths in your manifest match your actual file locations. If your manifest says "/images/icon-192.png" but the file is at "images/icon-192.png" (no leading slash), the browser will not find it and will show a warning. Test the paths by typing them directly into your browser address bar — if you see the image, the path is correct.

You can add more icon sizes if you want (144x144, 256x256, 384x384 are common), but 192 and 512 are the minimum. Each icon object needs src, sizes, and type fields. The type field should always be "image/png" for PNG files.

Link the manifest from your HTML

Your HTML file must tell the browser where to find the manifest. Add a single line to the <head> section of your index.html (or whichever page loads first):

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

Place this line near the top of your <head>, after the <meta charset> tag but it does not matter if it comes before or after other meta tags. The href path must match where you saved the manifest file. If your manifest is in a subfolder like /config/, change the href to "/config/manifest.json".

Without this link, the browser will never find your manifest, and your app will not be installable. This is the most common mistake — the manifest file exists but the HTML does not point to it.

Set colors and display options that match your design

The theme_color field controls the color of the browser toolbar and status bar on Android. The background_color field is the color shown behind your app while it loads. Both take hex color codes like "#2196F3" (blue) or "#ffffff" (white).

The orientation field locks the app to portrait or landscape. Set it to "portrait-primary" to force portrait mode, "landscape-primary" for landscape, or leave it out to let the user rotate freely. The scope field limits which pages count as part of your app — if you set it to "/app/", only URLs starting with /app/ will open in app mode.

You can also add categories (like "productivity" or "games"), screenshots for the install prompt, and shortcuts that appear in the app menu. These are optional but improve the install experience on some devices.

Test your manifest in Chrome DevTools

Open your site in Chrome, press F12 to open DevTools, and click the process tab. On the left sidebar, select Manifest. Chrome will show your manifest file, highlight any errors in red, and display warnings in yellow. Common errors include missing icon files, incorrect JSON syntax, and missing required fields.

If Chrome shows "No manifest detected", the link in your HTML is wrong or the manifest file does not exist. Check the file name (it must be exactly "manifest.json") and the href path in your <link> tag. If the syntax is invalid, Chrome will show the exact line with the problem.

You can also check the Install Prompts section in DevTools to see if your app meets the installability requirements. Chrome requires HTTPS (except on localhost), a valid manifest, a service worker, and icons in the sizes specified. Once all checks pass, the install button will appear in the address bar on Android or in the menu on desktop.

Common manifest.json mistakes and how to fix them

The most frequent errors are typos in icon paths, missing commas between JSON fields, and forgetting the link tag in HTML. Always validate your JSON syntax — a single missing comma will break the entire file. Use an online JSON validator or your code editor's built-in checker.

Another common issue is using relative paths without understanding how they work. If your manifest is at the root and your images are in /images/, use "/images/icon-192.png" (with a leading slash). If you use "images/icon-192.png" (no slash), the browser looks for /images/images/icon-192.png and fails.

Icon files must be PNG format and the exact size specified. A 192x192 icon scaled to 190x190 will not match the "192x192" declaration. Use an image editor or online tool to confirm the pixel dimensions before adding them to your manifest.

Frequently Asked Questions

Can I use JPG or WebP images instead of PNG for icons?

PNG is the safest choice because all browsers support it. WebP is newer and smaller but not supported on all devices. JPG does not support transparency, which looks bad on most home screens. Stick with PNG for maximum compatibility.

What happens if I don't include a manifest.json file?

Your site will still work as a normal website, but users cannot install it as an app. The install button will not appear, and the app will not have a home screen icon or custom colors. A manifest is only required if you want your site to be installable.

Do I need a service worker to use manifest.json?

A manifest alone does not require a service worker, but most PWAs use both. A service worker lets your app work offline and load faster. Chrome's installability check requires a service worker, so if you want the install prompt to appear, you need one.

Can I update the manifest after users install the app?

Yes. The browser checks the manifest each time the app updates, so changes to colors, name, or icons will explore to existing installations. However, changes to start_url or scope may not take effect until the user reinstalls.

What is the difference between name and short_name?

Name is the full app title shown during installation and in some system dialogs. Short_name appears on the home screen or app drawer where space is limited. If short_name is missing, the browser uses name and truncates it if needed.

This guide is for general information only and is not medical, financial, legal, or other professional advice. For decisions specific to your situation, consult a qualified professional. See our Editorial Policy.