Home

Awesome

ember-web-app

NOTICE: official repository moved to https://github.com/zonkyio/ember-web-app

This Ember addon helps you configure and manage the web app manifest and related meta tags needed to create a Progressive Web Application

From MDN

The web app manifest provides information about an application (such as name, author, icon, and description) in a text file. The purpose of the manifest is to install web applications to the homescreen of a device, providing users with quicker access and a richer experience.

Addon features:

See the documentation section below for more information.

Table of content

Installation

$ ember install ember-web-app

This generates a config/manifest.js configuration file.

Example

Having the following configuration file config/manifest.js

module.exports = function() {
  return {
    name: "Let's Cook",
    short_name: "Let's Cook",
    description: "An app for organizing your weekly menu and groceries list.",
    start_url: "/",
    display: "standalone",
    background_color: "#ffa105",
    theme_color: "#ffa105",

    icons: [
      {
        src: "/images/icons/android-chrome-192x192.png",
        sizes: "192x192",
        type: "image/png"
      },
      {
        src: "/images/icons/android-chrome-512x512.png",
        sizes: "512x512",
        type: "image/png"
      },
      {
        src: "/images/icons/apple-touch-icon.png",
        sizes: "180x180",
        type: "image/png",
        targets: ['apple']
      },
      {
        src: "/images/icons/mstile-150x150.png",
        element: "square150x150logo",
        targets: ['ms']
      }
    ],

    apple: {
      statusBarStyle: 'black-translucent'
    },

    ms: {
      tileColor: '#ffffff'
    }
  }
}

It will generate the following meta tags

index.html

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

<link rel="apple-touch-icon" href="/images/icons/android-chrome-192x192-883114367f2d72fc9a509409454a1e73.png" sizes="192x192">
<link rel="apple-touch-icon" href="/images/icons/android-chrome-512x512-af3d768ff652dc2be589a3c22c6dc827.png" sizes="512x512">
<link rel="apple-touch-icon" href="/images/icons/apple-touch-icon-36cba25bc155e8ba414265f9d85861ca.png" sizes="180x180">

<meta name="theme-color" content="#ffa105">

<meta name="apple-mobile-web-app-capable" content="yes">
<meta name="apple-mobile-web-app-title" content="Let's Cook">
<meta name="apple-mobile-web-app-status-bar-style" content="black-translucent">

<meta name="msapplication-config" content="/browserconfig.xml">

and the following manifest.webmanifest file

{
  "name": "Let's Cook",
  "short_name": "Let's Cook",
  "description": "An app for organizing your weekly menu and groceries list.",
  "start_url": "/",
  "display": "standalone",
  "background_color": "#ffa105",
  "theme_color": "#ffa105",
  "icons": [
    {
      "src": "/images/icons/android-chrome-192x192-883114367f2d72fc9a509409454a1e73.png",
      "sizes": "192x192",
      "type":"image/png"
    },
    {
      "src": "/images/icons/android-chrome-512x512-af3d768ff652dc2be589a3c22c6dc827.png",
      "sizes": "512x512",
      "type": "image/png"
    }
  ]
}

and the following browserconfig.xml file

<?xml version="1.0"?>
<browserconfig>
  <msapplication>
    <tile>
      <square150x150logo src="/images/icons/mstile-150x150.png"/>
      <TileColor>#ffffff</TileColor>
    </tile>
  </msapplication>
</browserconfig>

Configuration

Disable

You can disable the addon by adding a configuration option to ember-cli-build.js build file.

var EmberApp = require('ember-cli/lib/broccoli/ember-app');

module.exports = function(defaults) {
  var options = {
    'ember-web-app': {
      enabled: false
    }
  };

  var app = new EmberApp(defaults, options);

  return app.toTree();
};

Fingerprint

You can add fingerprint checksum to your manifest.webmanifest file by configuring broccoli-asset-rev.

The following example prepends with a custom domain and adds fingerprint checksum to the manifest.webmanifest file.

ember-cli-build.js

var EmberApp = require('ember-cli/lib/broccoli/ember-app');
var broccoliAssetRevDefaults = require( 'broccoli-asset-rev/lib/default-options' );

module.exports = function(defaults) {
  var options = {
    fingerprint: {
      extensions: broccoliAssetRevDefaults.extensions.concat(['webmanifest']),
      prepend: 'https://www.example.com/'
    }
  };

  var app = new EmberApp(defaults, options);

  return app.toTree();
};

Note that the replaceExtensions configuration from broccoli-asset-rev is updated internally by ember-web-app so you don't have to configure yourself on your project.

API documentation

This Ember addon generates a Web Application Manifest at build time using the config/manifest.js configuration file.

It also generates some compatibility meta tags for supporting vendor specific web application features like Apple's Web Content For Safari and Microsoft's Browser configuration schema that don't yet support the Web Application Manifest standard.

Internally, this addon takes into account four different types of targets for generating the web app manifest taking care of including some backward compatibility meta tags in order to support as many devices and browsers as possible. These targets are:

Not all targets are used for all properties (actually, most properties are not affected by the targets).

List of supported properties.

name

Provides a human-readable name for the application as it is intended to be displayed to the user, for example among a list of other applications or as a label for an icon.

Example

manifest.name = "dummy";
TargetGenerates
manifest{ "name": "dummy" }
apple<meta name="apple-mobile-web-app-title" content="dummy">
ms<meta name="application-name" content="dummy">
androiddoes not apply

short_name

Provides a short human-readable name for the application. This is intended for use where there is insufficient space to display the full name of the web application.

Example

manifest.short_name = "dummy";
TargetGenerates
manifest{ "short_name": "dummy" }
appledoes not apply
msdoes not apply
androiddoes not apply

background_color

Defines the expected background color for the web application.

Example

manifest.background_color = "#fff";
TargetGenerates
manifest{ "background_color": "#fff" }
appledoes not apply
msdoes not apply
androiddoes not apply

description

Provides a general description of what the web application does.

Example

manifest.description = "Lorem ipsum dolor";
TargetGenerates
manifest{ "description": "Lorem ipsum dolor" }
appledoes not apply
msdoes not apply
androiddoes not apply

dir

Specifies the primary text direction for the name, short_name, and description members.

Possible values:

Example

manifest.dir = "ltr";
TargetGenerates
manifest{ "dir": "ltr" }
appledoes not apply
msdoes not apply
androiddoes not apply

display

Defines the developer's preferred display mode for the web application.

Possible values:

The default value for display is browser when is not defined.

Example

manifest.display = "fullscreen";
TargetGenerates
manifest{ "display": "fullscreen" }
apple<meta name="apple-mobile-web-app-capable" content="yes">
msdoes not apply
androiddoes not apply

Note that for iOS the meta tag will be render with value yes only when display is fullscreen or standalone.

icons

Specifies an array of image objects that can serve as application icons in various contexts. For example, they can be used to represent the web application amongst a list of other applications, or to integrate the web application with an OS's task switcher and/or system preferences.

Image object members:

Example

icons: [
  {
    src: '/foo/bar.png',
    sizes: '180x180'
  },
  {
    src: '/bar/baz.png',
    sizes: '280x280',
    targets: ['apple']  // non-standard property
  },
  {
    src: '/bar/fav.png',
    sizes: '32x32',
    targets: ['favicon']
  },
  {
    src: '/bar/ms.png',
    element: 'square70x70logo', // non-standard property
    targets: ['ms'] // non-standard-property
  },
  {
    src: '/foo/monochrome.svg',
    safariPinnedTabColor: '#cc6600', // non-standard property
    targets: ['safari-pinned-tab'] // non-standard-property
  }
];
TargetGenerates
manifest{ "icons": [ { "src": "/foo/bar.png", "sizes": "180x180" } ] }
apple<link rel="apple-touch-icon" href="/foo/bar.png" sizes="180x180"> <link rel="apple-touch-icon" href="/foo/bar.png" sizes="280x280">
androiddoes not apply
favicon<link rel="icon" href="/bar/fav.png" sizes="32x32">
msicon in browserconfig.xml
safari-pinned-tab<link rel="mask-icon" href="/foo/monochrome.svg" color="#cc6600">

lang

Specifies the primary language for the values in the name and short_name members.

Example

manifest.lang = "es-UY";
TargetGenerates
manifest{ "lang": "es-UY" }
appledoes not apply
msdoes not apply
androiddoes not apply

orientation

Defines the default orientation for all the web application's top level browsing contexts.

Possible values:

Example

manifest.orientation = "portrait";
TargetGenerates
manifest{ "orientation": "portrait" }
appledoes not apply
msdoes not apply
androiddoes not apply

prefer_related_applications

Specifies a boolean value that hints for the user agent to indicate to the user that the specified related applications are available, and recommended over the web application.

Possible values:

Example

manifest.prefer_related_applications = true;
TargetGenerates
manifest{ "prefer_related_applications": true }
appledoes not apply
msdoes not apply
androiddoes not apply

related_applications

Specifies an array of "application objects" representing native applications that are installable by, or accessible to, the underlying platform.

Application object members:

Example

manifest.prefer_related_applications = true;
manifest.related_applications = [
  {
    "platform": "itunes",
    "url": "https://itunes.apple.com/app/example-app1/id123456789"
  }
];
TargetGenerates
manifest{ "prefer_related_applications": true, "related_applications": [{"platform": "itunes", "url": "https://itunes.apple.com/app/example-app1/id123456789" }] }
appledoes not apply
msdoes not apply
androiddoes not apply

scope

Defines the navigation scope of this web application's application context. This basically restricts what web pages can be viewed while the manifest is applied.

Example

manifest.scope = "/myapp/";
TargetGenerates
manifest{ "scope": "/myapp/" }
appledoes not apply
msdoes not apply
androiddoes not apply

start_url

Specifies the URL that loads when a user launches the application from a device.

Example

manifest.start_url = "./?utm_source=web_app_manifest";
TargetGenerates
manifest{ "start_url": "./?utm_source=web_app_manifest" }
appledoes not apply
msdoes not apply
androiddoes not apply

theme_color

Defines the default theme color for an application. This sometimes affects how the application is displayed by the OS.

Example

manifest.theme_color = "aliceblue";
TargetGenerates
manifest{ "theme_color": "aliceblue" }
appledoes not apply
msdoes not apply
android<meta name="theme-color" content="aliceblue">

Vendor specific properties (non-standard)

apple

Turns on/off the generation of Apple-specific meta and link tags.

Possible values:

Example

manifest.apple = false;
TargetGenerates
manifest{ "apple": false }
applereturns an empty string
msdoes not apply
androiddoes not apply

apple.webAppCapable

Overrides manifest.display for the generation of the apple-mobile-web-app-capable meta tag.

Possible values:

Example

manifest = {
  display: 'standalone',
  apple: {
    webAppCapable: false
  }
};
TargetGenerates
manifestdoes not apply
apple<meta name="apple-mobile-web-app-capable" content="yes">
msdoes not apply
androiddoes not apply

apple.statusBarStyle

Sets the style of the status bar for a web application in iOS

See Changing the Status Bar Appearance

Possible values:

Note that if set to default or black, the web content is displayed below the status bar. If set to black-translucent, the web content is displayed on the entire screen, partially obscured by the status bar.

Example

manifest.apple = {
  statusBarStyle: 'black-translucent'
};
TargetGenerates
manifestdoes not apply
apple<meta name="apple-mobile-web-app-status-bar-style" content="black-translucent">
msdoes not apply
androiddoes not apply

apple.precomposed

Adds precomposed suffix to Apple touch icons

See Precomposed Keyword for Apple touch icons

Possible values:

Example

manifest.apple = {
  precomposed: 'true'
};
TargetGenerates
manifestdoes not apply
apple<link rel="apple-touch-icon-precomposed" href="/images/icons/apple-touch-icon-192x192.png" sizes="192x192">
msdoes not apply
androiddoes not apply

apple.formatDetection

Adds format-detection meta tag if needed

See Safari HTML Reference

Possible values:

Example

manifest.apple = {
  formatDetection: {
    telephone: false
  }
};
TargetGenerates
manifestdoes not apply
apple<meta name="format-detection" content="telephone=no">
msdoes not apply
androiddoes not apply

ms

Turns on/off the generation of Microsoft-specific meta and link tags.

Possible values:

Example

manifest.ms = false;

ms.tileColor

Sets the <TileColor> property in browserconfig.xml.

See Browser configuration schema reference

Possible values:

Example

manifest.ms = {
  tileColor: '#ffffff'
};

Generating Icons

ember-web-app doesn't generate icons or images. If you want to automate the generation of icons starting from a master image, you can install ember-cli-image-transformer.

Managing all the various icon sizes and types can be overwhelming. One solution is to start with a base image which can be use to generate the necessary icon permutations for your environment. You can use ember-cli-image-transformer to handle this task.

If your manifest.js looks like this and needs a 192px and a 512px icon:

// config/manifest.js
export default function() {
  return {
    icons: [
      {
        src: '/assets/icons/appicon-32.png',
        sizes: `32x32`,
        targets: ['favicon']
      },
      ...[192, 280, 512].map((size) => ({
        src: `/assets/icons/appicon-${size}.png`,
        sizes: `${size}x${size}`
      }))
    ]
  };
}

You can start with a base brand-icon.svg image and automatically build the 192x192 and 512x512 versions by installing ember-cli-image-transformer and adding the necessary configuration to your ember-cli-build.js file:

// ember-cli-build.js
module.exports = function(defaults) {
  var app = new EmberApp(defaults, {
    'ember-cli-image-transformer': {
      images: [
        {
          inputFilename: 'lib/images/brand-icon.svg',
          outputFileName: 'appicon-',
          convertTo: 'png',
          destination: 'assets/icons/',
          sizes: [32, 192, 280, 512]
        }
      ]
    }
  });

Development

$ git clone https://github.com/san650/ember-web-app.git
$ cd $_
$ yarn          # (or npm install)

Running tests

$ npm test

Project's health

Build Status Ember Observer Score Maintainability dependencies Status devDependencies Status

License

ember-web-app is licensed under the MIT license.

See LICENSE for the full license text.