Gathering detailed insights and metrics for astro-webmanifest
Gathering detailed insights and metrics for astro-webmanifest
Makes it easy to add robots.txt, sitemap and web app manifest during build to your Astro app.
1.0.0
122
MIT
TypeScript
49.93 kB
Installations
npm install astro-webmanifestDeveloper Guide
BETA
Typescript
Yes
Module System
ESM
Node Version
18.17.1
NPM Version
9.6.7
Releases
62
astro-webmanifest@1.0.0
astro-webmanifest@1.0.0
Updated on Sep 08, 2023
astro-sitemap@1.0.0
astro-sitemap@1.0.0
Updated on Sep 08, 2023
astro-robots-txt@1.0.0
astro-robots-txt@1.0.0
Updated on Sep 08, 2023
astro-sitemap@0.6.0
astro-sitemap@0.6.0
Updated on Apr 19, 2023
astro-webmanifest@0.6.0
astro-webmanifest@0.6.0
Updated on Apr 19, 2023
astro-robots-txt@0.5.0
astro-robots-txt@0.5.0
Updated on Apr 19, 2023
Languages
3
TypeScript
JavaScript
Shell
TypeScript (96.28%)
JavaScript (3.55%)
Shell (0.17%)
Developer
alextim
Download Statistics
Total Downloads
0
Last Day
0
Last Week
0
Last Month
0
Last Year
0
GitHub Statistics
MIT License
122 Stars
377 Commits
7 Forks
1 Watchers
6 Branches
2 Contributors
Updated on Jul 11, 2025
Maintainers
1
Package Meta Information
Latest Version
1.0.0
Package Id
astro-webmanifest@1.0.0
Unpacked Size
49.93 kB
Size
12.67 kB
File Count
6
NPM Version
9.6.7
Node Version
18.17.1
Published on
Sep 08, 2023
Total Downloads
Cumulative downloads
Total Downloads
NaN
Last Day
0%
NaN
Compared to previous day
Last Week
0%
NaN
Compared to previous week
Last Month
0%
NaN
Compared to previous month
Last Year
0%
NaN
Compared to previous year
Weekly Downloads
Monthly Downloads
Yearly Downloads
Dependencies
3
Dev Dependencies
8
astro-webmanifest
This Astro integration generates a web application manifest, favicon, icons and inserts appropriate html into <head> section for your Astro project during build.
- Why astro-webmanifest
- Installation
- Usage
- Generation modes
- Configuration
- Localization
- Examples
- Contributing
- Changelog
Why astro-webmanifest?
The web app manifest provides information about a Progressive Web App (PWA) in a JSON text file. See Google's advice on web app manifest to learn more. Current standard for the manifest is on W3C. See also on MDN.
This integration provides numerous features beyond manifest configuration to make your life easier, they are:
- automatic icon generation - generates multiple icon sizes from a single source;
- favicon support;
- inserts all required
links andmetainto<head>section of generated pages; - legacy icon support (iOS);
- localization - provides unique manifests for path-based localization.
Each of these features has extensive configuration available so you are always in control.
Installation
Quick Install
The experimental astro add command-line tool automates the installation for you. Run one of the following commands in a new terminal window. (If you aren't sure which package manager you're using, run the first command.) Then, follow the prompts, and type "y" in the terminal (meaning "yes") for each one.
1# Using NPM 2npx astro add astro-webmanifest 3 4# Using Yarn 5yarn astro add astro-webmanifest 6 7# Using PNPM 8pnpx astro add astro-webmanifest
Then, restart the dev server by typing CTRL-C and then npm run astro dev in the terminal window that was running Astro.
Because this command is new, it might not properly set things up. If that happens, log an issue on Astro GitHub and try the manual installation steps below.
Manual Install
First, install the astro-webmanifest package using your package manager. If you're using npm or aren't sure, run this in the terminal:
1npm install --save-dev astro-webmanifest
Then, apply this integration to your astro.config.* file using the integrations property:
astro.config.mjs
1import webmanifest from 'astro-webmanifest'; 2 3export default { 4 // ... 5 integrations: [ 6 webmanifest({ 7 ... 8 }), 9 ], 10};
Then, restart the dev server.
Usage
The astro-webmanifest integration requires the config object to have at least a name option.
astro.config.mjs
1import { defineConfig } from 'astro/config';
2import webmanifest from 'astro-webmanifest';
3
4export default defineConfig({
5 // ...
6 integrations: [
7 webmanifest({
8 /**
9 * required
10 **/
11 name: 'Your App name',
12
13 /**
14 * optional
15 **/
16 icon: 'src/images/your-icon.svg', // source for favicon & icons
17
18 short_name: 'App',
19 description: 'Here is your app description',
20 start_url: '/',
21 theme_color: '#3367D6',
22 background_color: '#3367D6',
23 display: 'standalone',
24 }),
25 ],
26});Next put a source file your-icon.svg for icons generation to the src/images folder. This is optional.
Now, build your site for production via the astro build command. You should find your web manifest, all icons, favicons under dist/ folder!
Example of generated `manifest.webmanifest` file
manifest.webmanifest
1{ 2 "name": "Your App name", 3 "icons": [ 4 { 5 "src": "icons/icon-48x48.png", 6 "sizes": "48x48", 7 "type": "image/png" 8 }, 9 { 10 "src": "icons/icon-72x72.png", 11 "sizes": "72x72", 12 "type": "image/png" 13 }, 14 { 15 "src": "icons/icon-96x96.png", 16 "sizes": "96x96", 17 "type": "image/png" 18 }, 19 { 20 "src": "icons/icon-144x144.png", 21 "sizes": "144x144", 22 "type": "image/png" 23 }, 24 { 25 "src": "icons/icon-192x192.png", 26 "sizes": "192x192", 27 "type": "image/png" 28 }, 29 { 30 "src": "icons/icon-256x256.png", 31 "sizes": "256x256", 32 "type": "image/png" 33 }, 34 { 35 "src": "icons/icon-384x384.png", 36 "sizes": "384x384", 37 "type": "image/png" 38 }, 39 { 40 "src": "icons/icon-512x512.png", 41 "sizes": "512x512", 42 "type": "image/png" 43 } 44 ], 45 "short_name": "App", 46 "description": "Here is your app description", 47 "start_url": "/", 48 "theme_color": "#3367D6", 49 "background_color": "#3367D6", 50 "display": "standalone" 51}
Example of inserted HTML
All pages generated at build time will contain the following in the <head> section:
1<link rel="icon" href="/favicon-32x32.png" type="image/png" /> 2<link rel="icon" href="/favicon.svg" type="image/svg+xml" /> 3<meta name="theme-color" content="#3367D6" /> 4<link rel="manifest" href="/manifest.webmanifest" crossorigin="anonymous" />
Generations modes
There are 3 usage modes of astro-webmanifest integration: auto, hybrid and manual.
Automatic mode
For the most users - you need only the icon option to generate all required icons and favicons.
The integration has default icon preset to generate all icons.
astro.config.mjs
1import webmanifest from 'astro-webmanifest'; 2 3export default { 4 integrations: [ 5 webmanifest({ 6 name: 'Your app name', 7 icon: 'src/images/your-icon.svg', 8 }), 9 ], 10}; 11...
Hybrid mode
Additionally to the icon option you need to provide the icons array as a template to generate required icons.
No default icons. Only icons from the array will be created.
astro.config.mjs
1import webmanifest from 'astro-webmanifest'; 2 3export default { 4 integrations: [ 5 webmanifest({ 6 name: 'Your app name', 7 icon: 'src/images/your-icon.svg', 8 icons: [ 9 { 10 src: 'icons/icon-96x96.png', 11 sizes: '96x96', 12 type: 'image/png', 13 }, 14 { 15 src: 'icons/icon-256x256.png', 16 sizes: '256x256', 17 type: 'image/png', 18 }, 19 // add any other icon sizes 20 ], 21 }), 22 ], 23};
Manual mode
If you don't provide icon option, you will be fully responsible for manifest configuration.
You should create all icons and favicons manually and put them in a public folder.
astro.config.mjs
1import webmanifest from 'astro-webmanifest'; 2 3export default { 4 integrations: [ 5 webmanifest({ 6 name: 'Your app name', 7 icons: [ 8 { 9 src: 'icons/icon-96x96.png', 10 sizes: '96x96', 11 type: 'image/png', 12 }, 13 { 14 src: 'icons/icon-256x256.png', 15 sizes: '256x256', 16 type: 'image/png', 17 }, 18 // add any other icons 19 ], 20 }), 21 ], 22};
Configuration
To configure this integration, pass an object to the webmanifest() function call in astro.config.mjs.
:bulb: For this integration to work correctly, it is recommended to use the mjs or js configuration file extensions.
astro.config.mjs
1... 2export default defineConfig({ 3 integrations: [webmanifest({ 4 name: ... 5 })] 6});
The integration option object extends the Webmanifest type and optionally has config and locales properties as an object.
config property
outfile
| Type | Required | Default value |
|---|---|---|
String | No | manifest.webmanifest |
Template name for generated manifest file.
astro.config.mjs
1import webmanifest from 'astro-webmanifest'; 2 3export default { 4 integrations: [ 5 webmanifest({ 6 name: 'Your app name', 7 config: { 8 outfile: 'site.webmanifest', 9 }, 10 }), 11 ], 12};
See also Localization section.
indent
| Type | Required | Default value |
|---|---|---|
String | No | 4 spaces |
Leading characters for each line inserted into <head> to make the output more readable.
This only works when any of the insertFaviconLinks, insertThemeColorMeta, insertManifestLink, insertAppleTouchLinks properties are set to true.
astro.config.mjs
1import webmanifest from 'astro-webmanifest'; 2 3export default { 4 integrations: [ 5 webmanifest({ 6 name: 'Your app name', 7 config: { 8 // Empty string to cut off some bytes from html 9 indent: '', 10 // ... 11 }, 12 }), 13 ], 14};
eol
| Type | Required | Default value |
|---|---|---|
String | No | \n |
Trailing characters for each line inserted into <head> to make the output more readable.
This only works when any of the insertFaviconLinks, insertThemeColorMeta, insertManifestLink, insertAppleTouchLinks properties are set to true.
astro.config.mjs
1import webmanifest from 'astro-webmanifest'; 2 3export default { 4 integrations: [ 5 webmanifest({ 6 name: 'Your app name', 7 config: { 8 // Empty string to cut off some bytes from html 9 eol: '', 10 // ... 11 }, 12 }), 13 ], 14};
createFavicon
| Type | Required | Default value |
|---|---|---|
| Boolean | No | true |
Enable or disable a favicon generation.
This only works when the icon property is not empty.
astro.config.mjs
1import webmanifest from 'astro-webmanifest'; 2 3export default { 4 integrations: [ 5 webmanifest({ 6 name: 'Your app name', 7 config: { 8 icon: 'src/images/your-icon.png', 9 createFavicon: false, // default - true 10 // ... 11 }, 12 }), 13 ], 14};
insertFaviconLinks
| Type | Required | Default value |
|---|---|---|
| Boolean | No | true |
Enable or disable the favicon links insertion into <head>.
This only works when the icon property is not empty and createFavicon is true.
astro.config.mjs
1import webmanifest from 'astro-webmanifest'; 2 3export default { 4 integrations: [ 5 webmanifest({ 6 name: 'Your app name', 7 config: { 8 icon: 'src/images/your-icon.png', 9 insertFaviconLinks: false, // default - true 10 // ... 11 }, 12 }), 13 ], 14};
:exclamation: The final output reprocessing is used to insert the links into <head> sections. It can impact build times for large sites.
insertThemeColorMeta
| Type | Required | Default value |
|---|---|---|
| Boolean | No | true |
Enable or disable the meta insertion into <head>.
This only works when the theme_color property is not empty.
astro.config.mjs
1import webmanifest from 'astro-webmanifest'; 2 3export default { 4 integrations: [ 5 webmanifest({ 6 name: 'Your app name', 7 config: { 8 theme_color: '0xFFFF', 9 insertThemeColorMeta: false, // default - true 10 // ... 11 }, 12 }), 13 ], 14};
:exclamation: The final output reprocessing is used to insert the links into <head> sections. It can impact build times for large sites.
insertManifestLink
| Type | Required | Default value |
|---|---|---|
| Boolean | No | true |
Enable or disable the manifest link insertion into <head>.
astro.config.mjs
1import webmanifest from 'astro-webmanifest'; 2 3export default { 4 integrations: [ 5 webmanifest({ 6 name: 'Your app name', 7 config: { 8 insertManifestLink: false, // default - true 9 // ... 10 }, 11 }), 12 ], 13};
:exclamation: The final output reprocessing is used to insert the links into <head> sections. It can impact build times for large sites.
crossOrigin
| Type | Required | Default value |
|---|---|---|
| CrossOrigin | No | anonymus |
crossorigin attribute for the manifest link into <head>.
Available values for the CrossOrigin type are anonymous | use-credentials.
More details on MDN.
astro.config.mjs
1import webmanifest from 'astro-webmanifest'; 2 3export default { 4 integrations: [ 5 webmanifest({ 6 name: 'Your app name', 7 config: { 8 crossOrigin: 'use-credentials', // default - anonymus 9 // ... 10 }, 11 }), 12 ], 13};
insertAppleTouchLinks
| Type | Required | Default value |
|---|---|---|
| Boolean | No | false |
Enable or disable apple-touch-icon links into <head>.
iOS versions before 11.3 don't have support for web app manifest spec and don't recognize the icons defined in the webmanifest, so the creation of apple-touch-icon links into <head> is needed.
This only works when the icon property is not empty.
astro.config.mjs
1import webmanifest from 'astro-webmanifest'; 2 3export default { 4 integrations: [ 5 webmanifest({ 6 name: 'Your app name', 7 config: { 8 icon: 'src/images/your-icon.png', 9 insertAppleTouchLinks: true, // default - false 10 // ... 11 }, 12 }), 13 ], 14};
:exclamation: The final output reprocessing is used to insert the links into <head> sections. It can impact build times for large sites.
iconPurpose
| Type | Required | Default value |
|---|---|---|
| IconPurpose[] | No | undefined |
Available values for the IconPurpose type are badge | maskable | any |monochrome.
If provided it will be appended to the purpose property of generated icons.
This only works when the icon property is not empty.
astro.config.mjs
1import webmanifest from 'astro-webmanifest'; 2 3export default { 4 integrations: [ 5 webmanifest({ 6 name: 'Your app name', 7 config: { 8 icon: 'src/images/your-icon.png', 9 iconPurpose: ['badge', 'maskable'], 10 // ... 11 }, 12 }), 13 ], 14};
:exclamation: The final output reprocessing is used to insert the links into <head> sections. It can impact build times for large sites.
locales property
Record<string, Webmanifest> - key/object pairs. See usage in Localization section.
Type Webmanifest
| Name | Type | Required | Description |
|---|---|---|---|
icon | String | No | This is a source for automatically generated favicon and icons. It's a part of Webmanifest type.Icon format: JPEG, PNG, WebP, TIFF, GIF or SVG Icon size: at least as big as the largest icon being generated (512x512 by default). Icon geometry: preferably square, otherwise the results will be padded with transparent bars to be square. If the icon is empty - no automatic icon generation.See more about usage in Generation modes section. |
icons | Icon[] | No | See usage in Generation modes section. |
name | String | Yes | You must provide the name of your app. |
short_name | String | No | |
description | String | No | |
categories | String[] | No | |
lang | String | No | |
dir | Dir | No | auto | ltr | rtl |
iarc_rating_id | String | No | |
id | String | No | |
start_url | String | No | |
scope | String | No | |
theme_color | String | No | Source for meta in <head> |
background_color | String | No | |
display | Display | No | fullscreen | standalone | minimal-ui | browser |
display_override | Display[] | No | |
orientation | Orientation | No | any | natural | landscape | landscape-primary | landscape-secondary | portrait | portrait-primary | portrait-secondary |
protocol_handlers | ProtocolHandler[] | No | |
prefer_related_applications | Boolean | No | |
related_applications | RelatedApplication[] | No | |
screenshots | Image[] | No | |
shortcuts | Shortcut[] | No |
Type Icon
| Name | Type | Required | Description |
|---|---|---|---|
src | String | Yes | The path to the image file in URL form. |
sizes | String | No | Space-separated image dimensions. Syntax on MDN |
type | String | No | Media type of the image |
purpose | String | No | Space separated list of image purposes (IconPurpose type). See on W3C |
:bulb: If icon entry sizes property has value any or contains more then one size (96x96 128x128) in that case such entry will be excluded from automatic generation.
For Image, Shortcut, RelatedApplication, ProtocolHandler look on content of index.ts.
Also you can find the detailed descriptions on W3C and MDN.
Demo with advanced configuration is in this repo.
Localization
Localization allows you to create a unique manifest, icon set and <head> html for each individual language.
You need to provide locales property as a Record<string, Webmanifest>.
The integration uses the keys of the locales property to make the manifest name unique and to determine the page language by page's path.
The integration expects page paths in the following format: /{locale}{path}, where the locale is a key from the locales property.
Sample configuration below:
astro.config.mjs
1import webmanifest from 'astro-webmanifest'; 2 3export default { 4 integrations: [ 5 webmanifest({ 6 icon: 'src/images/logomark-light.svg', 7 8 name: 'Webmanifest i18n test', 9 short_name: 'Test', 10 description: 'This is the application description', 11 lang: 'en-US', 12 start_url: '/', 13 14 theme_color: '#3367D6', 15 background_color: '#3367D6', 16 display: 'standalone', 17 18 locales: { 19 es: { 20 name: 'Prueba Webmanifest i18n', 21 short_name: 'Prueba', 22 description: 'Esta es la descripción de la aplicación.', 23 lang: 'es-ES', 24 start_url: '/es', 25 }, 26 fr: { 27 name: 'Test i18n du manifeste Web', 28 short_name: 'Test', 29 description: "Ceci est la description de l'application", 30 lang: 'fr-CA', 31 start_url: '/fr', 32 }, 33 }, 34 }), 35 ], 36};
By this configuration three separate manifests will be generated:
manifest.webmanifest- for default language;manifest-fr.webmanifest- forfrlanguage;manifest-es.webmanifest- foreslanguage.
And language specific html will be inserted into <head> section of generated pages.
If you need a separate set of icons for each language, add the icon property.
astro.config.mjs
1import webmanifest from 'astro-webmanifest'; 2 3export default { 4 integrations: [ 5 webmanifest({ 6 name: 'Your app name', 7 icon: 'src/images/logo.svg', 8 lang: 'en-US', 9 // ... 10 locales: { 11 es: { 12 icon: 'src/images/logo-es.svg', 13 lang: 'es-ES', 14 // ... 15 }, 16 fr: { 17 lang: 'fr-CA', 18 // ... 19 }, 20 }, 21 }), 22 ], 23};
In this configuration, the default en language and fr language will have a common icon set, es will have its own icon set.
:bulb: The favicon will be the same for all languages. The source for generation will be taken from the default language.
You can explore a localization usage in this demo repo.
Examples
| Example | Source | Playground |
|---|---|---|
| basic | GitHub | Play Online |
| advanced | GitHub | Play Online |
| i18n | GitHub | Play Online |
Contributing
You're welcome to submit an issue or PR!
Changelog
See CHANGELOG.md for a history of changes to this integration.
No vulnerabilities found.
No security vulnerabilities found.