- Developer notes for IPFS Companion
If you're looking to develop on IPFS Companion, you should build the project from source. You will need NodeJS and Firefox. Make sure npm and firefox are in your PATH.
First, clone the ipfs-shipyard/ipfs-companion repository:
git clone https://github.com/ipfs-shipyard/ipfs-companion.gitThen, run this all-in-one dev build, which includes installing dependencies into the node_modules directory:
npm run dev-buildNote: Do not run
npm installornpm ciseparately. Thedev-buildscript handles dependency installation automatically and ensures correct build order.
Use this one-stop command to build, test and deploy the add-on in Firefox:
npm start # all-in-oneIf you run into issues, you can run each step manually to pinpoint where the process is failing:
npm run build # build runs bundle:firefox at the end, so manifest will be ok
npm run test # test suite
npm run firefox # spawn new FirefoxIt is also possible to load the extension manually:
- Enter
about:debuggingin the address bar - Click "This Firefox" in the left nav
- Click "Load Temporary Add-on..."
- Pick the file
add-on/manifest.json
Use this one-stop command to build, test and deploy the add-on in Chromium:
npm run dev-build chromium # all-in-oneYou can also build it to manually install:
npm run build bundle:chromium # last part is important: it overwrites manifestThen load the extension manually:
- Enter
chrome://extensionsin the address bar - Enable "Developer mode" using the toggle in the top right of the page
- Click "Load unpacked"
- Pick the directory
add-on
The regular run build command minifies code and strips source maps. It is possible to build in watch mode, which will rebuild a debug version of all changed bundles:
npm run build # do regular build first
npm run watch # watch for new changesNote: watch is a blocking command, so one needs to run it in a different terminal than firefox or chromium. Press ctrl+c to stop it.
Want to ensure prebuilt bundle does not include any additional code? Don't want to install JS dependencies such as NodeJS?
Do an isolated build inside of Docker!
Run the following command for ending up
with a built extension inside the build/ directory:
npm run release-buildIt is an alias for running ci:build script inside of immutable Docker image, which guarantees the same output on all platforms.
Each npm task can run separately, but most of the time, dev-build, test, and fix:lint are all you need.
npm run dev-build: Fast dependency install and buildnpm run dev-build firefox: All-in-one for Firefox: fast dependency install, build, run as temporary add-on in Firefoxnpm run dev-build chromium: All-in-one for Chromium: fast dependency install, build, run as temporary add-on in Chromiumnpm run firefox: Run as temporary add-on in Firefoxnpm run firefox:nightly: Run as temporary add-on in Firefox Nightly (uses one in./firefox/, seeget-firefox-nightlybelow)npm run chromium: Run as temporary add-on in Chromiumnpm run get-firefox-nightly: Fetch latest Firefox nightly build to./firefox/npm run build: Build the add-on (copy external libraries, create.zipbundles for Chrome and Firefox)npm run watch: Rebuild JS/CSS on file changes (run regularbuildfirst to ensure everything else is in place)npm run bundle:chromium: Overwrite manifest and package a generic, Chromium-compatible versionnpm run bundle:firefox: Overwrite manifest and package a Firefox-compatible versionnpm run build:rename-artifacts: Rename artifacts to include runtimes in filenamesnpm run ci: Run tests and build (with frozenpackage-lock.json)npm test: Run the entire test suitenpm run lint: Read-only check for potential syntax problems (run all linters)npm run fix:lint: Try to fix simple syntax problems (runstandardwith--fix, etc.)npm run lint:standard: Run Standard linter (IPFS JavaScript projects default to standard code style)npm run lint:web-ext: Run addons-linter shipped withweb-exttool
Release build shortcuts:
npm run dev-build: All-in-one: fast dependency install and buildnpm run release-build: Reproducible release build in docker with frozen dependencies
E2E tests:
npm run compose:e2e:prepare: Pull and build docker images for e2e testsnpm run compose:e2e:up: Start e2e test docker environmentnpm run compose:e2e:test: Run e2e tests in the docker environmentnpm run compose:e2e:down: Stop e2e test docker environment
E2E tests are run in a docker environment, so you need to have docker installed.
You can run the tests against either release or dev builds of the extension.
To download release builds of the extension, run:
./ci/e2e/download-release-builds.shNOTE: When using release builds, you can control the version of the extension by setting the IPFS_COMPANION_VERSION environment variable:
export IPFS_COMPANION_VERSION=x.y.zTo build dev versions of the extension, run:
npm run buildor (to perform the build inside a docker container):
npm run release-buildYou need to pull docker images for Kubo, Chromium and Firefox before running the tests.
You also need to build the docker image containing the e2e tests.
To do all of this, run:
npm run compose:e2e:prepareNOTE: You can control the versions of Kubo, Chromium and Firefox by setting the following environment variables:
export KUBO_VERSION=x.y.z
export CHROMIUM_VERSION=x.y.z
export FIREFOX_VERSION=x.y.zIMPORTANT: If you are running the tests on a ARM machine, you need to use a different Chromium image. To do this, run:
export CHROMIUM_IMAGE=seleniarm/standalone-chromium
export FIREFOX_IMAGE=seleniarm/standalone-firefoxTo run the tests, run:
npm run compose:e2e:testNOTE: You can control whether the browsers operate in headless mode as follows:
export TEST_HEADLESS=trueTo stop the docker environment, run:
npm run compose:e2e:down-
You can switch to an alternative Firefox version by overriding your
PATH:export PATH="/path/to/alternative/version/of/firefox/:${PATH}"
-
Using localization in IPFS Companion (running browsers with specific locale, etc)
Legacy versions 1.x.x were based on currently deprecated Add-On SDK (Firefox-only).
While it is not maintained any more, one can inspect, build, and install it using codebase from legacy-sdk branch. For historical background on the rewrite, see Issue #20: Move to WebExtensions.
Firefox for Android is capable of running some of the same extensions as the desktop version. This makes it very useful for experimenting with IPFS.
All channels are available at the Google Play Store:
For full installation instructions, see README/#install in the IPFS Companion repo.
You can also test the latest code locally on an emulator, or via USB on your own device. See below for details.
To run your extension in Firefox for Android, follow these instructions:
- Set up your computer and Android emulator or device (enable Developer Mode, USB debugging, etc.)
Build everything, and switch add-on/manifest.json to the Firefox profile:
npm run dev-build
npm run bundle:firefox
Then, with your device connected to your development computer, run:
web-ext run -s add-on --target=firefox-android
It will list all connected devices with their IDs. If the list is empty, go back to the setup step and try again.
Next, deploy your extension to the specific device:
web-ext run -s add-on --target=firefox-android --android-device=<device ID>
The first time you run this command, there may be a popup on your Android device asking if you want to grant access over USB.
The remote debug port will be printed to the console right after successful deployment:
You can connect to this Android device on TCP port <debug PORT>
The fastest way to connect is to open chrome://devtools/content/framework/connect/connect.xhtml in Firefox on the same machine you run web-ext from.