google-chrome-extension Getting started with google-chrome-extension

Remarks

Absolute minimum example

Any Chrome extension starts as an unpacked extension: a folder containing the extension's files.

One file it must contain is manifest.json , which describes the basic properties of the extension. Many of the properties in that file are optional, but here is an absolute minimum manifest.json file:

{
  "manifest_version": 2,
  "name": "My Extension",
  "version": "1.0"
}
 

Create a folder (for example, myExtension ) somewhere, add manifest.json as listed above to it.

Then, you need to load the extension in Chrome.

1. Open the chrome://extensions/ page, accessible though Menu > More tools > Extensions.
2. Enable Developer Mode with a checkbox in the top right, if it's not enabled already.
3. Click on Load unpacked extension... button and select the created myExtension folder.

That's it! Your first extension is loaded by Chrome:

Of course, it doesn't do anything yet, so it's a good moment to read an overview of extension architecture to start adding parts you need.

Important: When you do any changes to your extension, do not forget to return to chrome://extensions/ and press the Reload link for your extension after you make changes. In case of content scripts, reload the target page as well.

Background Page

Background pages are implicit pages which contain background scripts. A background script is a single long-running script to manage some task or state. It exists for the lifetime of your extension, and only one instance of it at a time is active.

You can declare it like this in your manifest.json :

"background": {
    "scripts": ["background.js"]
}
 

A background page will be generated by the extension system that includes each of the files listed in the scripts property.

You have access to all permitted chrome.* APIs.

There are two types of background pages: persistent background pages which is always open, and event pages that is opened and closed as needed.

If you want your background page to be non-persistent, you just have to set the persistent -flag to false:

"background": {
    "scripts": ["eventPage.js"],
    "persistent": false
}
 

This background script is only active if an event is fired on which you have a listener registered. In general you use a addListener for registration.

Example: The app or extension is first installed.

chrome.runtime.onInstalled.addListener(function() {
   console.log("The Extension is installed!");
});
 

Content Scripts

A content script is extension code that runs alongside a normal page.

They have full access to the web page's DOM (and are, in fact, the only part of the extension that can access a page's DOM), but the JavaScript code is isolated, a concept called Isolated World. Each extension has its own content script JavaScript context invisible to others and the page, preventing code conflicts.

Example definition in manifest.json :

  "content_scripts": [
    {
      "matches": ["http://www.stackoverflow.com/*"],
      "css": ["style.css"],
      "js": ["jquery.js", "myscript.js"]
    }
  ]
 

The attributes have the following meaning:

Attribute	Description
matches	Specifies which pages this content script will be injected into. Follows the Match Pattern format.
css	List of CSS files to be injected into matching pages.
js	List of JS files to be injected into matching pages. Executed in order listed.

Content scripts can also be injected on demand using chrome.tabs.executeScript , which is called Programmatic Injection.

See also

• Official documentation: Content Scripts
• Stack Overflow documentation: Content Scripts

Create a new tab

In the extension code you can use any chrome.* API if you decalared the required permissions. In addition, some API's works only from background pages, and some API's works only from content scripts.

You can use most of chrome.tabs methods declaring any permissions. Now we focus on chrome.tabs.create

_{Note: The new tab will be opened without any popup warning.}

chrome.tabs.create({
       url:"http://stackoverflow.com",
       selected:false  // We open the tab in the background
})
 

You can learn more about tab object, in the official chrome developer

Options Page

Options pages are used to give the user the possibility to maintain settings for your extension.

Version 2

Since Chrome 40 there is the possibility to have the option page as a predefined dialogue at chrome://extensions.

The way to define an option page in the manifest.json is like the following:

"options_ui": {
    "page": "options.html",
    "chrome_style": true
}
 

This option page will behave as a dialogue, it will open as a popup, where the options.html will be displayed. chrome_style will apply a Chrome stylesheet for style consistency reasons to your options page.

The options will be automatically exposed via the context menu of the extension button or the chrome://extensions page.

You can also open the options page programmatically, for example from a popup UI:

chrome.runtime.openOptionsPage();
 

Version 1 (deprecated)

Example definition in manifest.json :

"options_page": "options.html"
 

It is recommended to use Version 2 since the options_ui behavior will be soon applied to Version 1 options pages.

Storage

Normally the settings need to persist, so using chrome.storage API is recommended. The permissions can be declared like this in the manifest.json :

"permissions": [
   "storage"
]
 

Official documentation

• Options Page – Version 1
• Options Page – Version 2
• Storage API