Development Guide

Themes
Internationalization
- L10N
- RTL
Prefs
SVGs
Flow
Logging
Testing
- Unit Tests
- Integration Tests
Linting
- Lint JS
- Lint CSS
Colors
Configs
Hot Reloading
FAQ
Getting Help

Themes

The local debugger supports three themes:

Light	Dark	Firebug

Set a theme

You can change the theme by setting the theme field in your local.json to light, dark, or firebug. Walkthrough GIF

configs/local.json

{
  "theme": "dark"
}

Update a theme style

It is possible to add a theme specific selector. For example, this selector updates the dark debugger button colors:

.theme-dark .command-bar > span {
  fill: var(--theme-body-color);
}

Internationalization

The Debugger supports two types of internationalization RTL (right to left) layout and L10N (localization).

L10N

L10N is a global module with two methods getStr and getFormatStr.

L10N.getStr("scopes.header")
L10N.getFormatStr("editor.searchResults", index + 1, count)

Translated strings are added to the local strings file and m-c debugger properties file. We plan on removing strings.json soon!

Go checkout the L10N issues

RTL

RTL stands for right to left and is an important feature for arabic languages and hebrew. Here's what the debugger looks like right to left screenshot.

How do I set the Debugger to right to left?

Set the dir field in your the local config to either "rtl" or "ltr".

configs/local.json

"dir": "rtl"

How do I change how something looks in rtl?

We use postcss-bidirection to support logical CSS properties. In practice, this means we can write float:left or margin-inline-block: start, and it just works. Under the hood, float: left gets translated into two different CSS rules for html[dir="rtl"] and html:not([dir="rtl"]).

public/js/components/SourceFooter.css

html:not([dir="rtl"]) .source-footer .command-bar {
  float: right;
}

html[dir="rtl"] .source-footer .command-bar {
  float: left;
}

Prefs

User preferences are stored in Prefs. Prefs uses localStorage locally and firefox's profiles in the panel.

Setting a default value

pref("devtools.debugger.client-source-maps-enabled", true);

Adding a pref

const prefs = new PrefsHelper("devtools", {
  clientSourceMapsEnabled: ["Bool", "debugger.client-source-maps-enabled"],
});

Reading a pref

const { prefs } = require("./utils/prefs");
console.log(prefs.clientSourceMapsEnabled)

Setting a pref

const { prefs } = require("./utils/prefs");
prefs.clientSourceMapsEnabled = false;

SVGs

We use SVGs in DevTools because they look good at any resolution.

Adding a new SVG

add the SVG in assets/images
add it to Svg.js

diff --git a/assets/images/Svg.js b/assets/images/Svg.js
index 775aecf..6a7c19d 100644
--- a/assets/images/Svg.js
+++ b/assets/images/Svg.js
@@ -24,7 +24,8 @@ const svg = {
   "subSettings": require("./subSettings.svg"),
   "toggleBreakpoints": require("./toggle-breakpoints.svg"),
   "worker": require("./worker.svg"),
-  "sad-face": require("./sad-face.svg")
+  "sad-face": require("./sad-face.svg"),
+  "happy-face": require("./happy-face.svg")
 };

Using an SVG

import the Svg module
call Svg(<your-svg>)

diff --git a/src/components/Breakpoints.js b/src/components/Breakpoints.js
index 8c79f4d..6893673 100644
--- a/src/components/Breakpoints.js
+++ b/src/components/Breakpoints.js
@@ -4,6 +4,7 @@ const { bindActionCreators } = require("redux");
 const ImPropTypes = require("react-immutable-proptypes");
 const classnames = require("classnames");
 const actions = require("../actions");
+const Svg = require("./shared/Svg");
 const { getSource, getPause, getBreakpoints } = require("../selectors");
 const { makeLocationId } = require("../reducers/breakpoints");
@@ -89,6 +90,7 @@ const Breakpoints = React.createClass({
         key: locationId,
         onClick: () => this.selectBreakpoint(breakpoint)
       },
+      Svg("happy-face"),
       dom.input({
         type: "checkbox",
         className: "breakpoint-checkbox",

Styling an SVG element

You can style several SVG elements (svg, i, path) just as you would other elements.

fill is especially useful for changing the color

diff --git a/src/components/Breakpoints.css b/src/components/Breakpoints.css
index 5996700..bb828d8 100644
--- a/src/components/Breakpoints.css
+++ b/src/components/Breakpoints.css
@@ -69,3 +69,11 @@
 .breakpoint:hover .close {
   display: block;
 }
+
+.breakpoint svg {
+  width: 16px;
+  position: absolute;
+  top: 12px;
+  left: 10px;
+  fill: var(--theme-graphs-full-red);
+}

Flow

Adding flow to a file
Running flow
Missing Annotation
Where are types defined?
Checking flow coverage
Common Errors

Logging

Logging information can be very useful when developing, and there are a few logging options available to you.

To enable logging:

Create a local config file if you don't already have one
Edit your local config, changing the value of the logger type you want to see to true

  "logging": {
    "client": false,
    "firefoxProxy": false,
    "actions": true
  }

Restart your development server by typing ctrl+c in the Terminal and run yarn start again

Let's cover the logging types.

client - This option is currently unused.
firefoxProxy - This logger outputs a verbose output of all the Firefox protocol packets to your shell.
actions - This logger outputs the Redux actions fired to the browser console.

Testing

Your code must pass all tests to be merged in. Your tests should pass locally before you create a PR and the CI should run an automated test that also passes.

Here's how can run all the unit tests, lints, and integration tests at once:

yarn run test-all

Unit Tests

yarn test - Run tests with jest.

matchers
mock functions

Integration Tests

The Debugger integration tests are run in two contexts: firefox and the web. We recommend running the tests in the browser as it's an easier development environment.

Overview
Running the Tests
Gotchas
Writing Tests
Adding a New Test

Linting

Type	Command
all	`yarn run lint`
css	`yarn run lint-css`
js	`yarn run lint-js`
markdown	`yarn run lint-md`

Lint CSS

We use Stylelint to maintain our CSS styles. The .stylelintrc file contains the style definitions, please adhere to those styles when making changes.

To test your CSS changes run the command:

yarn run lint-css

Lint JS

We use eslint to maintain our JavaScript styles. The .eslintrc file contains our style definitions, please adhere to those styles when making changes.

To automatically fix many errors run the command:

yarn run lint-fix

Lint Markdown

We use remark to help lint our markdown. It checks for broken images, links, and a set of style rules.

Colors

The Debugger has a styleguide that we use to keep the colors consistent across tools and themes.

The common colors are represented as css variables in a devtools variables file. This lets define the colors for each theme: light, dark, firebug.

Making a color change

Most color changes can be made by finding a different css variable. For instance, --theme-splitter-color is often good for border colors. The advantage to using an existing variable is that you know it'll look good in all the themes.

When you need to update a variable, you should check to make sure it looks good in the other places it is being used. Often, it is more practicle to create a new variable.

It's helpful to share the changes as a themes table when you're done.

Checking Contrast

It's important to make sure that the contrast ratio is sufficient.

You can check the background / text color contrast ratio with this tool.

Configs

The Debugger uses configs for settings like theme, hotReloading, and feature flags.

The default development configs are in development-json. It's easy to change a setting in the Launchpad's settings tab or by updating your configs/local.json file.

Creating a new Feature Flag

When you're starting a new feature, it's always good to ask yourself if the feature should be added behind a feature flag.

does this feature need testing or introduce risk?
will this feature be built over several PRs?
is it possible we'll want to turn it off quickly?

It's easy to add a new feature flag to the project.

add the flag to development.json and firefox-panel.json
add isEnabled calls in the code

Here's an example of adding a new feature "awesome sauce" to the Debugger:

diff --git a/configs/development.json b/configs/development.json
index c82b299..d9de5f3 100755
--- a/configs/development.json
+++ b/configs/development.json
@@ -14,7 +14,8 @@
     "eventListeners": {
       "label": "Event Listeners",
       "enabled": false
     },
     "codeCoverage": {
       "label": "Code Coverage",
       "enabled": false
-    }
+    },
+    "awesomeSauce": {
+      "label": "Awesome Sauce",
+      "enabled": false
+    }
   },
   "chrome": {
     "debug": true,
diff --git a/configs/firefox-panel.json b/configs/firefox-panel.json
index c91b562..bf485bb 100644
--- a/configs/firefox-panel.json
+++ b/configs/firefox-panel.json
@@ -10,6 +10,7 @@
     "eventListeners": {
       "label": "Event Listeners",
       "enabled": false
     },
     "codeCoverage": {
       "label": "Code Coverage",
       "enabled": false
-    }
+    },
+    "awesomeSauce": {
+      "label": "Awesome Sauce",
+      "enabled": false
+    }
   }
 }

diff --git a/src/components/Editor/index.js b/src/components/Editor/index.js
index 038fd01..ea7a545 100644
--- a/src/components/Editor/index.js
+++ b/src/components/Editor/index.js
@@ -114,6 +114,10 @@ const Editor = React.createClass({
       return;
     }

+    if (isEnabled("awesomeSauce")) {
+      // sauce goops out of the breakpoint...
+    }
+

Restart your development server by typing ctrl+c in the Terminal and run yarn start again

Hot Reloading 🔥

🚧 Hot Reloading is currently broken as we need to upgrade react-hot-reloader 3.0 issue

Hot Reloading watches for changes in the React Components JS and CSS and propagates those changes up to the application without changing the state of the application. You want this turned on.

To enabled Hot Reloading:

Create a local config file if you don't already have one
edit hotReloading

diff --git a/configs/local.json b/configs/local.json
index fdbdb4e..4759c14 100644
--- a/configs/local.json
+++ b/configs/local.json
@@ -1,6 +1,6 @@
 {
   "theme": "light",
-  "hotReloading": false,
+  "hotReloading": true,
   "logging": {
     "actions": false
   },

Restart your development server by typing ctrl+c in the Terminal and run yarn start again

FAQ

Why not JSX

The reason is largely historical. Devtools historically has been developed inside the browser 1. The advantage of this approach is devtools could be written with ES6 and modules without a build step.

When we started the Debugger, we were not sure if we would keep webpack and the website workflow and did not want to re-write the JSX to raw JS.

Now that we have decided that working in github with webpack has a lot of benefits we could switch to JSX. We are open to switching if someone could help us do it, join the discussion here.

Getting Help

There are lots of helpful folks who'd be happy to answer your questions on slack.

Component		🐶 🐼 🐹
Editor		@jasonlaster @jbhoosreddy
Sources		@arthur801031 @bomsy
Call Stack		@zacqary @wldcordeiro
Scopes & Variables		@bomsy @arthur801031
Breakpoints		@wldcordeiro @jbhoosreddy
Product & UI		@clarkbw @jasonlaster

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

local-development.md

local-development.md

Development Guide

Themes

Set a theme

Update a theme style

Internationalization

L10N

RTL

Prefs

SVGs

Flow

Logging

Testing

Unit Tests

Integration Tests

Linting

Lint CSS

Lint JS

Lint Markdown

Colors

Making a color change

Checking Contrast

Configs

Creating a new Feature Flag

Hot Reloading 🔥

FAQ

Why not JSX

Getting Help

Files

local-development.md

Latest commit

History

local-development.md

File metadata and controls

Development Guide

Themes

Set a theme

Update a theme style

Internationalization

L10N

RTL

Prefs

SVGs

Flow

Logging

Testing

Unit Tests

Integration Tests

Linting

Lint CSS

Lint JS

Lint Markdown

Colors

Making a color change

Checking Contrast

Configs

Creating a new Feature Flag

Hot Reloading 🔥

FAQ

Why not JSX

Getting Help