chrome/common/extensions/docs/templates/articles/app_codelab_basics.html

<h1 id="create-chrome-app">
  <span class="h1-step">Step 1:</span>
  Create and Run a Chrome App
</h1>

<p>In this step, you will learn:</p>

<ul>
  <li>The basic building blocks of a Chrome App, including the manifest file and background scripts.</li>
  <li>How to install, run, and debug a Chrome App.</li>
</ul>

<p>
  <em>Estimated time to complete this step: 10 minutes.</em>
  <br>
  To preview what you will complete in this step, <a href="#launch">jump down to the bottom of this page &#8595;</a>.
</p>

<h2 id="app-components">Get familiar with Chrome Apps</h2>

<p>A Chrome App contains these components:</p>

<ul>
  <li>The <strong>manifest</strong> specifies the meta information of your app. 
    The manifest tells Chrome about your app, how to launch it, and any extra permissions that it requires.</li>
  <li>The <strong>event page</strong>, also called a <strong>background script</strong>, is 
    responsible for managing the app life cycle.
    The background script is where you register listeners for specific app events such as the launching and closing of the app's window.</li>
  <li>All <strong>code files</strong> must be packaged in the Chrome App. 
    This includes HTML, CSS, JS, and Native Client modules.</li>
  <li><strong>Assets</strong>, including app icons, should be packaged in the Chrome App as well.</li>
</ul>

<h3 id="manifest">Create a manifest</h3>

<p>Open your favorite code/text editor and create the following file named <strong>manifest.json</strong>:</p>

<pre data-filename="manifest.json">
{
  "manifest_version": 2,
  "name": "Codelab",
  "version": "1",
  "icons": {
    "128": "icon_128.png"
  },
  "permissions": [],
  "app": {
    "background": {
      "scripts": ["background.js"]
    }
  },
  "minimum_chrome_version": "28"
}
</pre>

<p>Notice how this manifest describes a background script named <em>background.js</em>.
You will create that file next.</p>

<pre>
"background": {
  "scripts": ["<b>background.js</b>"]
}
</pre>

<p>We'll supply you with an app icon later in this step:</p>

<pre>
"icons": {
  "128": "<b>icon_128.png</b>"
},
</pre>

<!-- <p>For more detailed information about the manifest file, refer to <a href="/apps/manifest">Manifest File Format</a> in the docs.</p>
 -->
<h3 id="background-script">Create a background script</h3>

<p>Create the following file and save it as <strong><em>background.js</em></strong>:</p>

<pre data-filename="background.js">
/**
 * Listens for the app launching then creates the window
 *
 * @see http://developer.chrome.com/apps/app.window.html
 */
chrome.app.runtime.onLaunched.addListener(function() {
  chrome.app.window.create('index.html', {
    id: 'main',
    bounds: { width: 620, height: 500 }
  });
});
</pre>

<p>This background script simply waits for the <a href="/apps/app_runtime.html#event-onLaunched">chrome.app.runtime.onLaunched</a> launch event for the application and executes the callback function:</p>

<pre>
<b>chrome.app.runtime.onLaunched</b>.addListener(function() {
  //...
});
</pre>

<p>When the Chrome App is launched, 
<a href="/apps/app_window.html#method-create">chrome.app.window.create()</a>
will create a new window using a basic HTML page (<em>index.html</em>) as the source.
You will create the HTML view in the next step.</p>

<pre>
<b>chrome.app.window.create</b>('<b>index.html</b>', {
  id: 'main',
  bounds: { width: 620, height: 500 }
});
</pre>

<p>Background scripts may contain additional listeners, windows, post messages, 
and launch data &mdash; all of which are used by the event page to manage the app. <!-- For more detailed information about background scripts, refer to <a href="app_lifecycle.html">Chrome App Lifecycle</a> in the docs. --></p>

<h3 id="html-view">Create an HTML view</h3>

<p>Create a simple web page to display a "Hello World" message to the screen and save it as <strong><em>index.html</em></strong>:</p>

<pre data-filename="index.html">
&lt;!DOCTYPE html&gt;
&lt;html&gt;
&lt;head&gt;
  &lt;meta charset="utf-8"&gt;
&lt;/head&gt;
&lt;body&gt;
  &lt;h1&gt;Hello, let's code!&lt;/h1&gt;
&lt;/body&gt;
&lt;/html&gt;
</pre>

<p>Just like any other web page, within this HTML file you can include 
additional packaged JavaScript, CSS, or assets.</p>

<h3 id="app-icon">Add an app icon</h3>

<p>Right-click and save this 128x128 image to your project folder as <strong><em>icon_128.png</em></strong>:</p>

<p align="center"><img src="{{static}}/images/app_codelab/icon_128.png" alt="Chrome App icon for this codelab" /></p>

<p>You will use this PNG as our application's icon that users will see in the launch menu. <!-- For more detailed information about app icons, refer to <a href="/apps/manifest/icons">Manifest - Icons</a> in the docs. --></p>

<h3 id="confirm-files">Confirm that you have created all your files</h3>

<p>You should have these 4 files in your project folder now:</p>

<figure>
  <img src="{{static}}/images/app_codelab/app-tutorial-files.png" alt="File folder screenshot"/>
</figure>

<h2 id="developer-mode">Install a Chrome App in developer mode</h2>

<p>Use <strong>developer mode</strong> to quickly load and launch your app without having to finalize your app as a distribution package.</p>

<ol>
  <li>Access <strong>chrome://extensions</strong> from the Chrome omnibox.</li>
  <li>Check off the <strong>Developer mode</strong> check box.</li>
</ol>

<figure>
  <img src="{{static}}/images/app_codelab/enable-developer-mode.gif" alt="Enable developer mode"/>
</figure>

<ol start="3">
  <li>Click <strong>Load unpacked extension</strong>.</li>
  <li>Using the file picker dialog, navigate to your app's project folder and select it to load your app.</li>
</ol>

<figure>
  <img src="{{static}}/images/app_codelab/load-unpacked-extensions.gif" alt="Load unpacked extensions"/>
</figure>

<h2 id="launch">Launch your finished Hello World app</h2>

<p>After loading your project as an unpacked extension, click <strong>Launch</strong> next to your installed app. A new standalone window should open up:</p>

<figure>
  <img src="{{static}}/images/app_codelab/step1-completed.png" alt="The finished Hello World app after Step 1"/>
</figure>

<p>Congratulations, you've just created a new Chrome App!</p>

<h2 id="devtools-debug">Debug a Chrome App with Chrome DevTools</h2>

<p>You can use the <a href="/devtools">Chrome Developer Tools</a> to inspect, debug, audit, and test your 
app just like you do on a regular web page.</p>

<p>After you make changes to your code and reload your app (<b>right-click &gt; Reload App</b>), check the DevTools console for any errors (<b>right-click &gt; Inspect Element</b>).</p>

<figure>
  <img src="{{static}}/images/app_codelab/inspect-element.png" alt="Inspect Element dialog box"/>
</figure>

<p>(We'll cover the <strong>Inspect Background Page</strong> option in <a href="app_codelab_alarms.html">Step 3</a> with alarms.)</p>

<p>The DevTools JavaScript console has access to the same APIs available to your app. 
You can easily test an API call before adding it to your code:</p>

<figure>
  <img src="{{static}}/images/app_codelab/console-log.png" alt="DevTools console log"/>
</figure>

<h2 id="recap">For more information</h2>

<p>For more detailed information about some of the APIs introduced in this step, refer to:</p>

<ul>
  <li>
    <a href="/apps/manifest" title="Read 'Manifest File Format' in the Chrome developer docs">Manifest File Format</a>
    <a href="#manifest" class="anchor-link-icon" title="This feature mentioned in 'Create a manifest'">&#8593;</a>
  </li>
  <li>
    <a href="/apps/manifest/icons" title="Read 'Manifest - Icons' in the Chrome developer docs">Manifest - Icons</a>
    <a href="#app-icon" class="anchor-link-icon" title="This feature mentioned in 'Add an app icon'">&#8593;</a>
  </li>
  <li>
    <a href="app_lifecycle.html" title="Read 'Manifest File Format' in the Chrome developer docs">Chrome App Lifecycle</a>
    <a href="#background-script" class="anchor-link-icon" title="This feature mentioned in 'Create a background script'">&#8593;</a>
  </li>
  <li>
    <a href="/apps/app_runtime.html#event-onLaunched" title="Read 'chrome.app.runtime.onLaunched' in the Chrome developer docs">chrome.app.runtime.onLaunched</a>
    <a href="#background-script" class="anchor-link-icon" title="This feature mentioned in 'Create a background script'">&#8593;</a>
  </li>
  <li>
    <a href="/apps/app_window.html#method-create" title="Read 'chrome.app.window.create()' in the Chrome developer docs">chrome.app.window.create()</a>
    <a href="#background-script" class="anchor-link-icon" title="This feature mentioned in 'Create a background script'">&#8593;</a>
  </li>
</ul>

<p>Ready to continue onto the next step? Go to <a href="app_codelab_import_todomvc.html">Step 2 - Import an existing web app &raquo;</a></p>