Desktop Apps with HTML5 and the Mozilla Web Runtime

Desktop Apps with HTML5

One of the best things about HTML is that it’s never “done”.  HTML has been with us longer than most of the development technologies that we consider commonplace. (.NET, ASP, Java, PHP, etc.)

The latest incarnation of HTML, HTML5 has been the source of a great deal of buzz in the software and information industries. When we say “HTML5”, we’re implicitly referring to the “stack” of  HTML/CSS/JavaScript.

At Mozilla we often refer to this collectively as the “Web Run-Time” or WebRT for short. Mozilla’s apps initiative, including the Web Runtime is documented here.

Skeptics like to say “HTML5 is not ready”. This week I saw an article declaring HTML5 won’t be “ready” for another 10 years. To which I ask “ready for what?” Of course there are many APIs that are still under development, but for many scenarios HTML5 is ready now. For many other scenarios its ready for development now and will be ready for general public use in the near future.

Recently the Mozilla Apps Native Install Experience was introduced to the Firefox Nightly Channel. (Read here for more information about the Firefox release channels.)

This functionality lets us install an HTML5 application with a native launching experience on Windows or Mac (Linux and Android coming).

One great way to do this is to simply list your app in the Mozilla Marketplace. The Marketplace will be open to the general public soon and developers can submit their app now at the Marketplace Ecosystem Portal. All you need besides an app to submit is a set of BrowserID credentials.

An HTML5 App that targets the Mozilla Web Runtime includes a manifest file.

The manifest is simply a JSON file that declares certain data about the application.

Here is the manifest file from a sample app. You can read more about the Mozilla App Manifest here.

      "version": "1.0",
      "name": "KO Round Timer",
      "description": "A Workout Timer for Fighting Athletes!",
      "icons": {
        "128": "/images/icon-128.png"
      "developer": {
        "name": "Joe Stagner",
        "url": ""
      "installs_allowed_from": [
      "default_locale": "en"

JSON does not need to be formatted with CRLFs. The above JSON is only formatted to simplify display.

Note line #12 above which specifies where the app can be installed from.

The Mozilla Web Runtime includes an apps object (winbow.navigator.mozApps) The mozApps object (currently implemented in Firefox Nightly on Windows and Mac) has a method to install an application. We’ll look at code that uses that API in a minute.

If you want your app to install from the Mozilla Marketplace you don’t need to write any install code. When you list your app in the marketplace, the marketplace creates a listing page for your app and that page includes an install button.

Mozilla Marketplace App Listing Page

The generated code that is invoked when the Install button is clicked tells the Runtime to install the app. The Runtime then fetches the manifest for the app and, among other things, checks to see it the app allows installation from whatever domain is requesting the install.

As you can see in the manifest listing above, line 14 specifies that the app may be installed from “”.

But you might want to let users install your application from other domains, for example your own web site.

You can see line 13 in our sample manifest, listed above, that “” is also specified as a valid “install from” location. I can specify as many domains as I like to be authorized to install the application from and wildcards are supported.

If we want to install the app from our own web site however, we need to implement the install logic ourselves.

We could create a page similar to the app listing page on the Mozilla Marketplace, or could make the app “self installing” meaning that we could implement installation logic in the app itself.

Take, for example, the Workout Timer app shown below.

K.O. Timer Screen Shot

Notice the row of navigation buttons at the bottom of the timer.

The last one to the right says “Install Me”.

The install button should only appear if the app is running in an environment that supports the mozApps runtime. Since this app (K.O. Timer) is an HTML5 app it can run in any HTML5 compliant browser but will only be “installable” if it is running in a browser / runtime with mozApps support.

We also don’t want the install button to appear if the app is already installed.

Here is a JavaScript method to test both runtime support and install state.

If runtime support is present and the app is not install then an install button is displayed.

In some scenarios you might choose to forgo the display of an optional install button and simply start the installer when the app is not already installed.

(This code is using jQuery)

function TestAppInstalled() {
    if ((!navigator.mozApps) || (!navigator.mozApps.getSelf)) {
        || Test to see if the Mozilla Apps Web Runtime is supported
        || HACK: Testing for either mozApps OR mozApps.getSelf is a
        || hack.
        || This is needed because some pre-beta versions of Firefox
        || have the object present but nit fully implemented.
        || TODO: Update when Firefox Desktop & Mobile are complete.

    var MyAppSelf = navigator.mozApps.getSelf();
    MyAppSelf.onsuccess = function() {
        if (! this.result) {
            // Application is not "installed"
        else {
             // This "MozApp" is already installed.
    MyAppSelf.onerror = function() {
        alert('Error checking installation status: ' +

When the user clicks on the install button the following code is called.

$('#InstallButton').click(function() {
    var installation = navigator.mozApps.install(
    installation.onsuccess = function() {
        alert("K.O. Timer has been successfully installed.....");
    installation.onerror = function() {
        alert("APP: The installation FAILED : " +;

So when the user navigates to the K.O. Timer app ( in a browser that supports mozApps (currently Firefox Nightly) and the user clicks on the “Install Me” button the mozApps runtime starts the installer.

KOTimer at Install Click

KOTimer at Install Click Closeup

After the user clicks “install” button in the dialog pictured above, the installer is called and, when completed, the user has a native launching experience.

On Windows you get a desktop shortcut.

Native Shortcut for HTML5 App

As well as a Start Menu item.

HTML5 app in the Windows Start Menu

And, of course the app is now in the user’s Mozilla MyApps collection.

Mozilla MyApps Collection

It’s important to remember that, while these launchers have been created on the user’s system the application itself still exists in the cloud. A developer can choose to add “off line” functionality to their application by other HTML5 features like AppCache, LocalStorage or IndexedDB.

The ability to provide native launchers for HTML5 apps, coupled with the huge HTML5 apps distribution mechanism that will be available when the Mozilla Marketplace become available to the general public (in the near future), creates great opportunity for developers building standards based apps.

About Joe Stagner

More articles by Joe Stagner…


  1. Adam Messinger

    When I first read about WebRT, I got the impression it would offer a chromeless environment for “HTML5” apps. Is that something that’s on the way? I ask because a current project of mine would benefit from a kiosk-like experience. I could use the full-screen API, but a curious or mischievous user could exit full-screen and go to a new URL with the browser’s address field. This might cause confusion for the next user on the same machine.

    I’m also curious if Mozilla has considered offering Gecko as an installable runtime for local *or* cloud-based HTML5 apps that could be distributed through any app store for installation on mobile or desktop platforms. One could use PhoneGap to build such a cross-platform mobile app, but there are still non-trivial platform compatibility headaches to get around. It would be nice to develop for one platform that runs an installable app in many environments.

    May 14th, 2012 at 13:56

    1. Jean-Yves Perrier

      HTML5 Apps on the Mozilla market that is in test will be installable everywhere, both on mobile and on the desktop. Gecko won’t be an installable runtime, the apps will just start Firefox which will have a special mode.

      May 14th, 2012 at 15:22

    2. Kevin Dangoor

      @Adam: I’ll note for the first part of your message that apps installed from Firefox do indeed run a chromeless runtime when you launch them. So, you don’t have a Gecko runtime you can install from other app stores (some of which wouldn’t even support the installation of such a runtime), but you do get that kind of “separate, chromeless app” experience after installation.

      May 14th, 2012 at 19:15

      1. Adam Messinger

        Does the issue with some app stores come when the runtime environment is a separate installation? Would it still be a problem if a “compilation” step bundled the runtime up as part of the installable app? Thanks for the clarification — I’m not very familiar with the policies of the various app stores.

        May 16th, 2012 at 09:42

  2. Jon Galloway

    Interesting post, Joe! (also, hi!)

    How does this relate to XUL?

    May 14th, 2012 at 15:11

  3. Adam Messinger

    Thanks for the follow-up, Kevin and Jean-Yves. I look forward to seeing how WebRT develops and using it at some point in the future.

    May 14th, 2012 at 20:14

  4. antistress

    This is very detailed thanks.

    You’ve written :
    “This functionality lets us install an HTML5 application with a native launching experience on Windows or Mac (Linux and Android coming).”
    “On Windows you get a desktop shortcut. as well as a Start Menu item.”

    Will the application use the Desktop Menu Specification ( to allow the application to sit in the Linux menu application (which is divided into categories : Graphics/Utility/Game/Office etc.) ?

    May 15th, 2012 at 03:33

    1. Joe Stagner

      Thanks. We’re hoping to tackle native installer for Linux this summer so the details are not set. We’d be open to community contributions so if you’re interested, let me know and I can make the right connections for you. -Joe

      May 15th, 2012 at 07:26

      1. antistress

        Thank you for the answer but, as a simple user, i don’t have any special skill : i’m only aware that menus on Linux (GNOME, KDE, Xfce…) are built using that freedesktop spec. Therefore if the author doesn’t classified its application (Graphics/Utility/Game/Office etc.) it will be hard to get Linux integration.
        Moreover this classification would be useful to categorize applications on Mozilla web-appstore

        May 15th, 2012 at 08:25

  5. pd



    May 15th, 2012 at 08:02

  6. pd

    This is quite interesting. Over the years Mozilla has seemed to be almost schizophrenic about making a web-dev-friendly native-OS-aware codebase available. I remember debates about xulRunner, there was Prism – which now seems like a half-hearted WebRT … I’m Sure there’s a few more references I’m forgetting. Now it seems as though attitudes have been flipped in that it’s fine to look at using Firefox essentially as a multi-platform application development platform with native OS desktop/home screen awareness.

    The question for me is, AFAIK Electrolysis had been de-prioritized yet Jean-Yves you refer to apps running Firefox in a ‘special mode’ but there only being one runtime. If a user has one Firefox binary installed as their main browser, but also one or more web apps, when they run the browser and then also the webapp, will both be using the same Firefox binary executable? If so, how is that different from multi-process support which Electrolysis was supposed to provide? Are apps, in effect, merely going to open a secondary (or more) Firefox window without the default chrome UI?

    I use Firefox about 12 hours a day and have done for many years but despite countless hours of developer work, I still get the situation now and then where the chrome is closed by the process stubbornly refuses to die. Inadvertently I then click the Firefox shortcut again and I don’t get a proper browser window but rather a session-less secondary window. I might not be explaining this too well but I’m just wondering if that sort of behavior can be cleanup up and therefore save potential confusion for web app users.

    May 15th, 2012 at 08:26

    1. Kevin Dangoor

      Electrolysis has been deprioritized. I don’t know all of the technical details, but I have an installed app running right now on my machine (Mac OS). It is running in a separate process with, I believe, a separate profile. That means that an app will be isolated:

      1. from other browsing (thus helping to ensure responsiveness in the face of bad behavior on both ends)

      2. from buggy add-ons

      3. from cruft that has been built up in the profile.

      Running with a new, clean profile can fix some weird behavior that is seen in old, crufty profiles. The “Reset Firefox” feature[1] might help with that odd behavior you’re reporting. Just be sure to only try it in beta at the moment.


      May 16th, 2012 at 06:07

      1. alexleduc

        It’s nice to see that some someone are giving some thought to the “crufty profile” issue. This reminds me all too much of the Windows registry and how a crufty registry could slow down your machine (especially in the Windows 9x days).

        It’s easy for us techies to export our bookmarks and start a new profile from scratch when we feel FF is starting to act buggy/slow, but a normal user would just conclude that “FF is too bloated these days, I’m switching to something else”.

        June 5th, 2012 at 06:08

  7. Iraê

    I use firefox aurora all the time. I opened the console and verified that the api is there for use. I cloned the openwebapps repo and hosted the mozball example on my local server only to find-out that it uses an old style api. Also, I subscribed to the mozilla marketplace but I need approval from someone before I am able to join.

    Am I missing something or just running a hello world app has a high entrance barrier for now? I currently work building an desktop app with web technologies and in the proccess of choosing between Apace Cordova (formerly Phonegap) Chromium Embeded Framework, Mozilla Prism and I am interested at looking into MozillaWebRT but information is really sparse and hard to test.

    Is there some example already hosted somewhere or in a repository that I can checkout? Or coping, pasting and hacking is the only way for now? =)

    May 15th, 2012 at 10:18

  8. Iraê

    BTW, my profile for approval is:

    May 15th, 2012 at 10:22

  9. julio

    Hi, this id an amazing article, but this feature of desktop año will runing on Windows 8, i reffer Windows8 and the metro style año


    May 16th, 2012 at 17:21

  10. Joe Stagner

    Hi Irae,

    AT this moment you need Firefox Nightly.


    June 4th, 2012 at 06:38

  11. Ken Walker

    I wrote up a short tutorial on how to test out your web app using Orion. Write for the cloud in the cloud!

    July 9th, 2012 at 11:46

  12. LY

    Hello, Your article is very useful for me to research Mozilla App Publishing & Installing.

    And I want to confirm one thing that whether B2G has the same process of Publishing & Installing with the above content in your article?

    I consider it’s all the same for both Firefox(PC) App and B2G App.

    Thank you!

    July 26th, 2012 at 23:17

  13. Joe Stagner

    Hi LY,

    Yes the process will be the same for Firefox OS (B2G)


    July 27th, 2012 at 06:32

  14. Tankred Hase


    Will there be a secure signature of the installed app signed with the private key of the developer (like in Chrome packaged apps)? Thanks


    July 28th, 2012 at 23:22

  15. Hayk Saakian

    What’s the state of this technology?

    I’ve read about Firefox packaged apps, but these are Firefox OS only right now.

    When can we expect a proper PC release?

    January 19th, 2013 at 22:19

    1. Robert Nyman

      It’s being worked on in general, and currently you can try it in the Firefox OS Simulator or Nightly versions of Firefox.

      January 22nd, 2013 at 01:57

Comments are closed for this article.