Getting Started

This tutorial walks you through creating a simple extension. To complete this tutorial, you must have Windows; Linux and Mac don't yet support extensions.

Get your browser ready

To develop extensions for Google Chrome, you need to set up your browser:

  1. Subscribe to the Dev channel of Google Chrome for Windows.
  2. Create a separate profile for testing (optional but highly recommended). Having a testing profile means that you can use Google Chrome (with your default profile) for everyday browsing, even if your extension has horrible bugs.

Create and load an extension

In this section, you'll write a toolstrip — an extension that puts a bit of UI into the toolbar at the bottom of the Google Chrome window.

  1. Create a folder somewhere on your computer to contain your extension's code. We'll assume the folder is located at c:\myext, but it can be anywhere.
  2. Inside your extension's folder, create a text file called manifest.json, and put this in it: 
    { "name": "My First Extension", "version": "1.0", "description": "The first extension that I made.", "toolstrips": [ "my_toolstrip.html" ] }
  3. In the same folder, create a text file called my_toolstrip.html, and put this in it: 
    <div class="toolstrip-button"> <span>Hello, World!</span> </div>
  4. Load the extension:
    1. Change the shortcut that you use to start the browser (or create a new one) so that it has the --enable-extensions and --load-extension flags. For example, if your extension is at c:\myext, your shortcut might look something like this: 
      chrome.exe --enable-extensions --load-extension="c:\myext"
    2. Exit Google Chrome. If you have a separate profile for testing, you only need to exit the browser instances that use the testing profile.
    3. Double-click the shortcut to start the browser.

    Note: For details on changing shortcut properties, see Creating and Using Profiles.

You should see the UI for your extension at the bottom left of the browser, looking something like this:

default appearance initial onhover appearance final onhover appearance

Your extension's button is automatically styled to look like it belongs in the browser. If you put the cursor over the button, the button gets a nice, rounded edge, just like the buttons in the bookmark bar. After a while, a tooltip comes up, identifying the extension.

[PENDING: troubleshooting info should go here. what are symptoms of common typos, including misnamed files? what are the symptoms if you don't have the dev channel?]

Add code to the extension

In this step, you'll make your extension do something besides just look good.

  1. Inside your extension's folder, create a text file called hello_world.html, and add the following code to it:

    CSS and JavaScript code for hello_world

  2. Edit my_toolstrip.html, so that it has the following code: 

    <div class="toolstrip-button" onclick="window.open('hello_world.html')"> <span>Hello, World!</span> </div>
  3. Restart the browser to load the new version of the extension.
  4. Click the button. A window should come up that displays hello_world.html.

It should look something like this:

a window with a grid of images related to HELLO WORLD

If you don't see that page, try the instructions again, following them exactly. Don't try loading an HTML file that isn't in the extension's folder — it won't work!

Debug the extension

You can use the browser's built-in developer tools to view your extension's code, display debugging output, and debug your extension.

  1. Edit my_toolstrip.html, so that it has the following code: 

    <script> function helloWorld() { var hwFile = 'hello_world.html'; console.log("in helloWorld()"); window.open(hwFile); } </script> <div class="toolstrip-button" onclick="helloWorld();"> <span>Hello, World!</span> </div>

    The relocated code still has the same effect, but now it has some debugging output, thanks to the call to console.log().

  2. Restart the browser, so that it loads your new version of the extension.
  3. Right-click the Hello, World! button (at the bottom left) to bring up the Developer Tools window for this instance of your toolstrip. The window should look something like this:

  4. Click the Scripts button. If necessary, choose my_toolstrip.html from the list of scripts. The result should be something like this:

  5. Set a debugging breakpoint at the window.open() statement by clicking 5 in the left column:

  6. Click the Console button (second from left, at the bottom of the Developer Tools window) so that you can see both the code and the console.

  7. Back in the main browser window, click the Hello, World! button, so that the extension begins executing. You should see the output of console.log() along with the line number, and execution should stop just before the call to window.open().

    The Call Stack area at the right of the tools window shows that the helloWorld() method was called by an anonymous function that was called by onclick. Anywhere in the Call Stack or console that you see a file and line number (for example, "my_toolstrip.html:4"), you can click that text to see the relevant line of code.

  8. In the upper right part of the tools window, scroll down (if necessary) until you can see the local scope variables. This section shows the current values of all variables in the current scope. For example, you can see that hwFile is a local variable that has the value "hello_world.html".

  9. Click the buttons at the upper right of the window to resume execution or to step through the code. Once the call to window.open() returns, the main browser window should open a new tab that displays the contents of hello_world.html.

You now know how to load and debug an extension!

Summary

[PENDING: Summarize what we did, what it means, what else we would've done if this were a real extension (e.g. package it), and where to find more information. Suggest where to go next.]