templates/articles/apps.html

<h1>Packaged Apps</h1>


<p class="warning">
<b>Warning: </b>
All content in this doc refers to the legacy version of packaged apps.
Your legacy packaged apps will still work,
but you won't have access to any of the new APIs.
Check out the new version of
<a href="../apps/about_apps">Chrome Apps</a>;
otherwise, you're missing out!
</p>

<p>
This page talks about packaged apps&mdash;how
you implement them,
and how they're different from
extensions and ordinary web apps.
</p>

<h2 id="overview">Overview</h2>

<p>
A packaged app is a web app
that's bundled into a <code>.crx</code> file
and can use Chrome extension features.
You build a packaged app just like you build an extension,
except that a packaged app can't include a
<a href="browserAction">browser action</a> or
<a href="pageAction">page action</a>.
Instead, a packaged app includes at least one HTML file
within its <code>.crx</code> file
that provides the app's user interface.
</p>

<p>
Packaged apps are a type of
<a href="http://code.google.com/chrome/apps/">installable web app</a>&mdash;a
web app that can be installed in Chrome.
The other type of installable web app is a
<a href="http://code.google.com/chrome/apps/docs/developers_guide">hosted app</a>,
which is an ordinary web app with a bit of additional metadata.
</p>

<p>
If you're developing a web app for the Chrome Web Store,
you might want to use a packaged app
instead of a hosted app if any of the following are true:
</p>

<ul>
  <li>
    You don't want to run a service to host your app.
  </li>
  <li>
    You want to build an app that works really well offline.
  </li>
  <li>
    You want tighter integration with Chrome,
    using the extension APIs.
  </li>
</ul>

<p>
To learn more about
the differences between web apps and websites,
extensions and packaged apps, and packaged apps and hosted apps,
read these:
</p>

<ul>
  <li> <a href="http://code.google.com/chrome/webstore/docs/choosing.html">Choosing an App Type</a> </li>
  <li> <a href="http://code.google.com/chrome/apps/articles/thinking_in_web_apps.html">Thinking in Web Apps</a> </li>
  <li> <a href="http://code.google.com/chrome/webstore/articles/apps_vs_extensions.html">Extensions, Packaged Apps, and Hosted Apps in the Chrome Web Store</a> </li>
</ul>


<h2 id="manifest"> The manifest </h2>

<p>
A packaged app's manifest can have any field
that's available to extensions,
except for "browser_action" and "page_action".
In addition, a packaged app's manifest <b>must</b>
have an "app" field.
Here is a typical manifest for a packaged app:
</p>

<pre data-filename="manifest.json">
{
  "name": "My Awesome Racing Game",
  "description": "Enter a world where a Vanagon can beat a Maserati",
  "version": "1",
  <b>"app": {
    "launch": {
      "local_path": "main.html"
    }
  },</b>
  "icons": {
    "16": "icon_16.png",
    "128": "icon_128.png"
  }
}
</pre>

<p>
The "app" field has one subfield, "launch",
which specifies the <em>launch page</em> for the app&mdash;the
page (HTML file bundled into the <code>.crx</code> file)
that the browser goes to when the user clicks the app's icon
in the New Tab page.
The "launch" field can contain the following:
</p>

<dl>
  <dt>local_path:</dt>
    <dd><em>Required.</em>
    Specifies the launch page
    as a relative path referring to a file
    in the <code>.crx</code> package.
    </dd>
  <dt>container:</dt>
    <dd> The value "panel" makes the app appear
    in an app panel.
    By default, or when you specify "tab",
    the app appears in a tab.

    <!-- PENDING: In the overview
    (or somewhere else before here)
    we should show and define both app panels and tabs.
    We should link to that place from here. -->
    </dd>
  <dt>height:</dt>
    <dd>
    If the container is set to "panel",
    this integer specifies the height
    of the panel in pixels.
    For example, you might specify
    <code>"height":400</code>.
    Note that you don't use quotation marks in the value.
    This field specifies the height of the area
    to display contents in;
    window decorations add a few more pixels to the total height.
    If the container isn't a panel, this field is ignored.
    </dd>
  <dt>width:</dt>
    <dd>
    Similar to "height",
    but specifies the width of the panel.
    </dd>
  </dd>
</dl>

<p>
Packaged apps usually provide a 16x16 icon
to be used as the favicon for
tabs that contain app's pages.
They also should provide a 128x128 icon,
but not a 48x48 icon.
See the manifest documentation for the
<a href="manifest/icons">"icons" field</a>
for more information.
</p>

<p>
For further details on what a packaged app's manifest can contain, see the
<a href="manifest">manifest documentation</a>.
</p>

<h2 id="next">What next?</h2>

<p>
Read the <a href="overview">Overview</a> to learn
basic concepts about extensions.
</p>

<p class="backtotop"><a href="#top">Back to top</a></p>