Firefox applications are easy

Originally published January 25, 2014.

So, you may have heard about this Firefox OS thing (hereafter abbreviated fxos). If you don’t know anything about it, be sure to take a quick look at the beautiful landing page!

What you may not know is that the apps you write for Firefox OS can also be installed on any desktop computer capable of running Firefox (on Aurora or Nightly), and as a pseudo-native application on Android via Firefox Beta for Android.

This is a big win. Even better, it’s dead simple to create these apps! Write one webapp, create one manifest.webapp (essentially a .json file that expects certain properties), create some media queries for the mobile device, and you’ve instantly got what feels a lot like a cross-platform native application.

Creating a fxos hosted app

I’ll try to walk us through the minimal subset of things we need to accomplish in order to get a functional cross-platform Firefox app. This guide won’t walk you through the creation of a webapp itself — it assumes you’ve completed this process already and just want to make your application available as a fxos hosted app.

Essentially, once we’re done, you can install this on the platforms that support fxos, and once you launch the app, it’ll be like visiting a web page without the browser chrome.

Step 1: Application Manifest

To start with, we’ll need a manifest.webapp. This is a very simple file that is essentially just a json description of your application. For a comprehensive resource on all fields, be sure to look at the MDN article on manifest.webapp, but I aim to go over the most useful and necessary ones.

To get us started, please take a look at the one below:

manifest used by echoplexus

version is a human readable version string. You’ll use this if you ever need to update your `manifest.webapp`

name is simply the name of the application. In OSX, once you install, will be added to your /Applications. In Firefox Beta for Android, it will appear on your homescreen as name.

installs_allowed_from specifies which sites may install your application. You generally don’t need to worry about this unless you want to restrict who may install apps on your behalf, or you want to charge money for apps.

description: is a short description. As far as I can tell, this might just mainly be for bots, but the Firefox Marketplace will attempt to use this to pre-populate your application submission.

icons is super important. Expect to need copies in at least 30x30, 60x60, 128x128, with potentially many more variants being necessary.

permissions sets out which APIs your app intends to use. The bonus of this type of app architecture is that most permissions tie in to familiar web technologies; for example, in echoplexus, to display native notifications we can use the HTML5 Notification API.

Step 2: Validate your manifest

You’ve written a JSON blob, but now you should really validate it. Thankfully, there’s a nice manifest validator available from Mozilla. It seems to be necessary to pass this validator if you intend on submitting your application to the Firefox Marketplace. I’d recommend attempting to get your manifest passing, even if it’s inconvenient, for your own developer sanity.

Step 3: Setting the proper MIME type

It’s definitely a good idea to follow the recommendation and set up your server for the proper MIME type for the manifest.webapp. Essentially, this lets your browser know what it should do with the file.

In express, this is accomplished with:

express.static.mime.define {'application/x-web-app-manifest+json': ['webapp']}

If you’re serving up files from a static directory, or proxying through another webserver, you might handle it on that level. Google can help you here.

Step 4: Creating a simple page to install the webapp

Once you’ve created the manifest, validated it, and added the MIME type, you’re almost done. Now you just need a simple way to install the app.

At this point, you should probably load up the Firefox application manager (about:app-manager) in Firefox, add an application (pointing to your localhost), and try to install it onto the fxos simulator. If this fails, your manifest might not be valid (re-validate), your MIME type might be messed (look at the headers in the Chrome inspector), or you simply specified the wrong URL.

If all looks good, you can create a very simple page using the mozApps API to help your users install your application. This way, they needn’t necessarily download it via the Firefox Marketplace (or other marketplace).

Here’s a really simple html file that will install your webapp.manifest from a Firefox app capable browser:

install.html from echoplexus

The above should look fairly straightforward. This assumes you’re hosting your manifest in roughly the same spot as the above install.html.

It’s worth noting that only Mozilla is supporting this at the moment, so you may want to conditionally show any Install buttons depending on the browser. In practice, a good check is:

if (navigator.mozApps) {
// … show install button …

Once you click the button, you should see a shelf dropdown. The app is now available immediately to use!


Who thought making a cross-platform application would be so simple? It doesn’t feel nearly as straight-forward to create a Chrome extension, and with Chrome extensions it feels like you’re limited to fighting with the Chrome App store, forcing you to create an account.

Firefox’s app architecture let’s anyone create their own app store. In general, it’s a lot more open. Of course, this shifts the burden of checking the app for maliciousness to the user.

It seems that if you’re using a hosted app, you only need to install the manifest once. Once installed, periodically upon launching, it will grab the latest html, js, images required.

It’s very nice that many of the APIs are already ones we’re familiar with as web developers. Chances are, if you had a web application that needed desktop notifications, for example, it’ll just work when creating a fxos app. This, in my opinion, is a great boon.

As a result, it feels incredibly liberating to create these applications. Most of the work is already done for you, if you started out creating a webapp. In the ideal world, you don’t need to worry about the platform specific oddities in order to perform useful OS-integrated actions.

I just hope that as time passes, Chrome and others come to adopt this format for webapps, freeing web developers from the shackles of device specific APIs.

I’ve created a fxos app for echoplexus. You can try it out by visiting the home page with Nightly, Aurora, or Firefox Beta for Android. It was available on the Firefox Marketplace but I don’t have time to maintain it to their standards.


- one webapp, multiple platforms
- very simple and straight-forward app creation process for web developers; you’re already making apps!
- app management tools come with firefox (visit about:app-manager), and the fxos simulator is easily obtained with a no-hassle installation. This means that testing your application is also dead simple


- support for native APIs is not quite there yet; most will be available only for fxos
- it’s essentially just a webview in Android
- you have to make media queries, and it can be difficult to cram device specific logic into one app. Caveat: nothing is stopping you from making a mobile-only webapp
- only supported by Mozilla at the moment
- the Firefox developer tools can feel clunky and unfamiliar