LanguagesYour First Chrome Packaged App

Your First Chrome Packaged App content and product recommendations are editorially independent. We may make money when you click on links to our partners. Learn More.

Getting started building your first Chrome packaged app is quick and easy if you have a good handle on HTML, CSS and JavaScript. All you have to do is create an HTML page, add a small amount of boilerplate JavaScript and create a manifest.json file that describes how your app should work with Chrome.

Getting Started

Most web programmers grew up in the era of generating web pages using PHP, ASP.NET Web Forms or MVC. Installable HTML5 apps don’t work this way and need to be built as stand-alone HTML, CSS and JavaScript files. As you start developing your app, you can create your html files on any folder on your disk and just launch them right in the browser from disk by double clicking the HTML.

The HTML Page

Overall the kind of HTML you can use in a Chrome packaged app is fairly typical but there is one major restriction. You can’t include any inline script in your packaged app. This will take some getting used to for most web developers that are accustomed to using HTML snippets like the one below, which will not work in a chrome packaged app.

<button onclick="alert('Hello!');">Say

Instead of including inline script, you will need to include the scripts your page needs as external references in the head tag. Because you can’t include inline script, you will need to make sure your HTML includes the necessary IDs or class references for your external script to be able to tie into.

 <script src="jquery-1.9.1.min.js" type="text/javascript"></script>

 <script src="hello.js" type="text/javascript"></script>
<button id="HelloButton">Say Hello!</button>

It is also worth noting that the “alert()” function isn’t supported in Chrome packaged apps. If you need to pop a message that blocks the UI, I would highly recommend the jQuery based blockUI plugin.

Your chrome packaged apps can have multiple HTML pages that the user can navigate between using relative references.

The script utilized by this HTML uses some basic jQuery to attach to the button’s click event and pop a message using the blockUI plugin when the user clicks it.

$(document).ready(function() {
$("#HelloButton").bind("click", function() {
$.blockUI({ message: "Hello there" });


The background.js file is the Chrome packaged app equivalent of a “void main()”. It is the entry point of your application where you can either do whatever background tasks your app does or to present your user interface to the user.

In the example below, you define a function that will be called when your app’s “onLaunched” event is fired. To launch a window, call “” passing in your application’s main UI HTML file as a parameter along with any other window parameters you like. () {'container.html', {
 'width': 800,
 'height': 600

The API has a few options worth exploring. In addition to the width/height options you can also set minWidth/minHeight and maxWidth/maxHeight to set a lower and upper bound on the size of the window that can be created.

There is also a property called “singleton” that if set to true will make sure that there is only one of that window in existence at a time. This is extremely useful if your app won’t behave correctly if there are multiple instances running at the same time.

Creating the Chrome Packaged App Manifest

The manifest defines the name of your application, how it is launched, and what kinds of rights your app needs in order to function properly. You create the manifest by just creating a new text file called, “manifest.json” in the same directory as your html page.

The basic behavior of how your application behaves is defined inside of the “app” property, which defines whether or not your application will be launched in a new tab, in a popup, as an overlay on an existing page or to run in the background with no UI at all. In this example, you are referencing a type of “background” and setting the script to the background.js script defined in the previous section.

The permissions section defines what permissions your app needs in order to run successfully. These permissions are a mix of elevated browser permissions such as the ability to store unlimited amounts of data, or directly access the user’s clipboard and URLs of web sites your app needs to be able to access.

 "name": "Hello Example",
 "version": "0.99",
 "app": {
 "background": {
 "scripts": ["./scripts/background.js"]
 "icons": {
 "16": "icon_16.png",
 "128": "icon_128.png"
 "permissions":["unlimitedStorage","storage", "*"],

It is worth noting that the manifest requires your JSON be extremely strictly formatted, including quotes around all of the keys. For a complete list of all of the available manifest properties, consult the Chrome extensions developer site.

The icons property lets you define different icons for your application. If you put a large icon here it can automatically be scaled down depending on the size of icon needed (favicon, task bar sized, new tab launching screen). Although it can automatically scale down, you might want to have a simpler version of your icon at the smaller sizes so it is still legible.

The version property and numbering scheme is a “major.minor” format that you can use whatever numbers you like to describe your version number. You will need to always increment it up because if you try to release a version with a lower version number, Chrome won’t auto-update your app.

Loading it up in Chrome

To load your extension in chrome, launch Tools->Extensions. In the screen that appears, you will need to check the “Developer Mode” checkbox. Once you have done so, you can click the “Load unpacked extension” button and point it to your Chrome Packaged App.

The Tools -> Extensions screen
Figure 1. The Tools -> Extensions screen

Once your packaged app has loaded, you can launch it by opening a new tab and launching it from the Chrome Apps screen. Running your application from an “unpacked” mode will allow you to change the underlying HTML/CSS files as much as you need while you develop, and immediately see the results just by clicking the refresh button.

Make note of the ID letters assigned to your application on the Extensions tab. This ID is how other apps can link back to your app. For example, if you are connecting to a web service using OAuth that has a return link, you need to set the return link similar to the format below.


All of the normal debugging tools available in Chrome are available to debug your packaged app including the elements and JavaScript console window.

Packaging Your App

Once you’re ready to distribute your app, you can package your extension as a CRX file by clicking the “Pack extension” button in the extensions tab. You can allow it to generate a private key for you the first time but it is important to keep control of your private key because you will need it later if you want to ship updates.

To load the CRX file on someone else’s computer, you will need to check the “Developer Mode” checkbox. After the developer mode checkbox has been set, you can just drag and drop the file onto Chrome and it will install immediately.

To submit your app to the Chrome web store, you just zip up the directory, and send it into Google’s App Store submission process. Google only charges $5 for an app store submission and you could get your app in front of thousands of users in minutes!

About the Author:

David Talbot has over 14 years of experience in the software industry and specializes in building rich UI web applications. He is also the author of Applied ADO.NET and numerous articles on technology. He can be reached at

Get the Free Newsletter!

Subscribe to Developer Insider for top news, trends & analysis

Latest Posts

Related Stories