Local build setup

First-time setup

Requirements

• Node 14
• pre-commit to manage git hooks. brew install pre-commit

Optional:

• web-ext to launch the extension in a separate browser profile. npm install --global web-ext

Install Dependencies and Pre-commit Hooks

npm install
pre-commit install

Environment Configuration File

Create a browsers/.env.development file to hold custom environment variables for development builds:

# Ask the the project maintainer for the key. This key is used for the `key` entry in the 
# Chrome extension manifest to make the extension id match what's expected by app.pixiebrix.com
# @see https://developer.chrome.com/docs/extensions/mv2/manifest/key/
CHROME_MANIFEST_KEY=

Development

Running automated tests

npm test

Building the extension

You can build the project locally by running:

npm run build

If you making changes to the code, you can instead create a development build that continuously watches for changes:

npm run watch

The build tool (webpack), will send a system notification each time it has rebuilt extension.

NOTE: the build tool does not do "hot-reloading". You will have to refresh the page you're on to see any changes.

Loading the extension in the Browser

Manual

You can load it manually from the browsers/dist folder.

If you are using npm run watch, the build tool will automatically reload the extension on each change. So you only have to load the extension manually once. (However, if you you make changes to the manifest, you may need to toggle the extension off and on for Chrome to reload the manifest)

web-ext

You can use web-ext to watch for the changes and reload the extension automatically:

web-ext run                   # Opens Firefox
web-ext run --target chromium # Opens Chrome

Some information about the web-ext:

• $ web-ext run can be run at the root of the project, will automatically use browsers/dist
• Any files in that folder causes the whole extension to be reloaded (some contexts like the DevTools and tabs additional need manual reloading)
• Generates a new temporary profile for each run
• The profile can be preserved, but they advise not preserving your personal profile as these profiles are less secure. Use a custom path instead
• You can use the same path for both browsers, as suggested below

web-ext run \
  --keep-profile-changes \
  --firefox-profile ~/.cache/web-ext-profile

web-ext run \
  --keep-profile-changes \
  --chromium-profile ~/.cache/web-ext-profile \
  --target=chromium

Since these commands are personalized (the path part), we suggest creating local aliases instead of adding them to package.json

A workflow for using web-ext:

• Terminal tab with npm run watch
• Terminal tab with startchrome (my alias for web-ext)

Account Setup

Create a PixieBrix account

1. Navigate to the PixieBrix webapp
2. Connect your Google or Microsoft account. If you don't have a Google/Microsoft account, contact a project maintainer to receive a email/password login
3. You should see a message "You have PixieBrix version XXX installed!". If you don't double check the CHROME_MANIFEST_KEY environment variable (described above)

Choose an account alias

1. Follow the quick start to Open the Page Editor and choose an account alias/username

IDE Configuration

IntelliJ

Webpack Configuration

For module resolution to work properly, you need to specify which Webpack configuration to use

Use the configuration at browsers/webpack.config.js

Submitting Pull Requests

NOTE: if pre-commit modifies a file during a commit, you have to re-stage it in the Git commit.