Skip to content
Branch: master
Find file History
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.

Sourcegraph browser extension

code style: prettier license

chrome version chrome users chrome rating\


The Sourcegraph browser extension adds tooltips to code on GitHub, Phabricator, and Bitbucket. The tooltips include features like:

  • symbol type information & documentation
  • go to definition & find references (currently for Go, Java, TypeScript, JavaScript, Python)
  • find references

🚀 Install: Sourcegraph for Chrome

🚀 Install: Sourcegraph for Firefox

It works as follows:

  • when visiting e.g., the extension injects a content script (inject.bundle.js)
  • there is a background script running to access certain chrome APIs, like storage (background.bundle.js)
  • a "code view" contains rendered (syntax highlighted) code (in an HTML table); the extension adds event listeners to the code view which control the tooltip
  • when the user mouses over a code table cell, the extension modifies the DOM node:
    • text nodes are wrapped in (so hover/click events have appropriate specificity)
    • element nodes may be recursively split into multiple element nodes (e.g. a &Router{namedRoutes: contains multiple code tokens, and event targets need more granular ranges)
    • We assume syntax highlighting takes care of the base case of wrapping a discrete language symbol
    • tooltip data is fetched from the Sourcegraph API
  • when an event occurs, we modify a central state store about what kind of tooltip to display
  • code subscribes to the central store updates, and creates/adds/removes/hides an absolutely positioned element (the tooltip)

Project layout

  • src/extension/
    • Entrypoint for browser extension builds. (Includes bundled assets, background scripts, options)
  • src/browser
  • src/libs/
    • Isolated pieces of the browser extension. This contains code that is specific to code hosts and separate "mini applications" included in the browser extension such as the src omnibar cli.
  • src/libs/phabricator/
  • src/shared/
    • Code shared by the extension and the libraries. Ideally, nothing in here should reach into any other directory.
  • src/config/
    • Polyfills and configuration/plumbing code that is bundled via webpack. The configuration code adds properties to window that make it easier to tell what environment the script is running in. This is useful because the code can be run in the content script, background, options page, or in the actual page when injected by Phabricator and each environment will have different ways to do different things.
  • src/e2e/
    • E2e test suite.
  • scripts/
    • Development scripts.
  • webpack
    • Build configs.
  • build
    • Generated directory containing the output from webpack and the generated bundles for each browser.


  • node
  • yarn
  • make


For each browser run:

yarn run dev

To only build for a single browser (which makes builds faster in local development), set the env var TARGETS=chrome or TARGETS=firefox.

Now, follow the steps below for the browser you intend to work with.


  • Browse to chrome://extensions.
  • If you already have the Sourcegraph extension installed, disable it by unchecking the "Enabled" box.
  • Click on Load unpacked extensions, and select the build/chrome folder.
  • Browse to any public repository on GitHub to confirm it is working.
  • After making changes it is necessary to refresh the extension. This is done by going to chrome://extensions and clicking "Reload".

Add dist folder

Updating the bundle

Click reload for Sourcegraph at chrome://extensions

Firefox (hot reloading)

In a separate terminal session run:

yarn global add web-ext
yarn run dev:firefox

A Firefox window will be spun up with the extension already installed.

Updating the bundle

Save a file and wait for webpack to finish rebuilding.


The window that is spun up is completely separate from any existing sessions you have on Firefox. You'll have to sign into everything at the begining of each development session(each time you run yarn run dev:firefox). You should ensure you're signed into any Sourcegraph instance you point the extension at as well as GitHub.

Firefox (manual)

  • Go to about:debugging
  • Select "Enable add-on debugging"
  • Click "Load Temporary Add-on" and select "firefox-bundle.xpi"
  • More information

Updating the bundle

Click reload for Sourcegraph at about:debugging


  • Unit tests: yarn test
  • E2E tests: yarn test:e2e


Deployment the Chrome web store happen automatically in CI when the bext/release branch is updated. Releases are also uploaded to the GitHub releases page and tagged in git.

To release the latest commit on master, ensure your master is up-to-date and run

git push origin master:bext/release
You can’t perform that action at this time.