-
Install Node 10.18.1+ (e.g. using node version manger)
-
Clone the repo, install dependencies, start the dev environment:
git clone https://github.com/mozilla/FirefoxColor.git cd FirefoxColor npm install npm start
This will start a webpack-dev-server instance at port 8080 and start a watcher that will rebuild the browser extension with every file change.
-
In Firefox 57 + open
about:debugging
and load thebuild/extension/manifest.json
file. -
Visit
http://localhost:8080
to see the web-based theme editor - changes should be relayed through the temporarily installed add-on and alter the browser theme
Note: If you have problems seeing the editor at http://localhost:8080/
on
your computer, it's possible that you already have some other service using
port 8080. You can change the port that Firefox Color uses for local development:
- For Linux & OS X:
PORT=9090 npm start
- For Windows:
.\node_modules\.bin\cross-env PORT=9090 npm start
This example switches to port 9090, but you can supply a different port as needed.
There are a few environment variables used in building the site and extension that are handy to know about:
PORT
- (default:8080
) Port at which the webpack dev server will start upNODE_ENV
- (default:production
) setting todevelopment
will enable some features for development workSITE_URL
- (default:http://localhost:8080
) the URL where the web app is hostedSITE_ID
- (default: empty string) the ID of the site for the extension - e.g. "", "local", "stage", "dev"DOWNLOAD_FIREFOX_UTM_SOURCE
- host name used in metrics when the button to download Firefox is clickedLOADER_DELAY_PERIOD
- (default:2000
) delay in ms used for web site loader, can be set to0
during development to make the site appear faster but with visual glitches
Deploying a development release consists of pushing to the development
branch
on this repo. Production release consists of pushing to the production
branch.
Upon push, CircleCI will run the following steps, as defined in the .circleci/config.yml
file:
-
Run gen-environment.sh to define the
SITE_URL
andADDON_URL
applicable to the current branch. -
Run code linter
-
Build the site for the current branch
-
Build the add-ons for all build targets (development, stage, release).
-
Run tests on the current branch.
When pushed to the development branch, npm run deploy
is run to deploy the site to Github Pages.
Signing depends on WEB_EXT_API_KEY
and WEB_EXT_API_SECRET
environment
variables being set for use by web-ext sign
. Deployment depends on
GH_TOKEN
being set with a personal access token from GitHub. These
are currently configured in CircleCI to support deployment after successful
test runs.
The script npm run xpi
in package.json
generates unsigned xpi files, which
are added to build/web
(and published to the root of SITE_URL
by CircleCI),
on all branches (development, stage, production). These XPIs can be loaded at
about:debugging
for manual testing.
firefox-color-dev-unsigned.xpi
- test with Development (testing only).firefox-color-stage-unsigned.xpi
- test with Stage (testing only).firefox-color-unsigned.xpi
- test with Production (release candidate).
After passing QA, the XPI can be published by manually uploading it to AMO. Every release requires a version bump, because version numbers cannot be reused.
Environment | Github Branch | URL |
---|---|---|
Development | development | https://mozilla.github.io/FirefoxColor/ |
Stage | stage | https://color.stage.mozaws.net/ |
Production | production | https://color.firefox.com/ |
-
Coming from AMO
- The user clicks on the "Install" button and after granting permissions, a new tab opens to the addon's home page.
-
Coming from the addon's home page: The user can click on the "Get Firefox Color" button which will direct the user to a page from where the add-on can be installed, usually AMO.
- Further reading for themes
- Other addons for managing & creating themes
- An example of a more complex dynamically changing theme
- Dynamic theme with colors based on favicon
- Theme API
- Hacks post on Theme API
- theme.getCurrent()
- Useful for other webextensions to match current theme colors with their own UIs
- Maybe pre-load web page with current theme?
- https://developer.mozilla.org/en-US/Add-ons/WebExtensions/API/theme/getCurrent