ipfs-companion

Developer notes for IPFS Companion

Table of contents

Build from source

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.

Clone and build

First, clone the ipfs/ipfs-companion repository:

 git clone https://github.com/ipfs/ipfs-companion.git

Then, run this all-in-one dev build, which includes installing dependencies into the node_modules directory:

npm run dev-build

Note: Do not run npm install or npm ci separately. The dev-build script handles dependency installation automatically and ensures correct build order.

Build and run in Firefox

Use this one-stop command to build, test and deploy the add-on in Firefox:

npm start        # all-in-one

If 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 Firefox

It is also possible to load the extension manually:

  1. Enter about:debugging in the address bar
  2. Click “This Firefox” in the left nav
  3. Click “Load Temporary Add-on…”
  4. Pick the file add-on/manifest.json

Build and run in Chromium

Use this one-stop command to build, test and deploy the add-on in Chromium:

npm run dev-build chromium        # all-in-one

You can also build it to manually install:

npm run build            # build the extension
npm run bundle:chromium  # overwrite add-on/manifest.json for Chromium

Then load the extension manually:

  1. Enter chrome://extensions in the address bar
  2. Enable “Developer mode” using the toggle in the top right of the page
  3. Click “Load unpacked”
  4. Pick the directory add-on

Run build on file changes

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 changes

Note: 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.

Reproducible build in Docker

To build without installing the JS toolchain locally, and to confirm the bundle carries no extra code, build inside Docker.

Run this to produce a built extension in the build/ directory:

npm run release-build

It is an alias for running ci:build script inside of immutable Docker image, which guarantees the same output on all platforms.

Useful tasks

Each npm task can run separately, but most of the time, dev-build, test, and fix:lint are all you need.

Release build shortcuts:

E2E tests:

Running E2E tests

E2E tests are run in a docker environment, so you need to have docker installed.

Preparing extension builds

You can run the tests against either release or dev builds of the extension.

To download release builds of the extension, run:

./ci/download-release-artifacts.sh

NOTE: 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.z

To build dev versions of the extension, run:

npm run build

or (to perform the build inside a docker container):

npm run release-build

Preparing the docker environment

The tests run a Kubo node in one container and Playwright with a headless Chromium in another. Pull the Kubo image and build the test image with:

npm run compose:e2e:prepare

NOTE: Pin the Kubo version with the KUBO_VERSION environment variable:

export KUBO_VERSION=x.y.z

Running the tests

npm run compose:e2e:test

Stopping the docker environment

To stop the docker environment, run:

npm run compose:e2e:down

Other tips

Legacy Firefox (< 53) and XUL-compatible browsers

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.

Using IPFS Companion on Firefox for Android

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.

Install Firefox for Android

All channels are available at the Google Play Store:

Install IPFS Companion

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.

Hot-deploy over USB

To run your extension in Firefox for Android, follow these instructions:

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.

Debugging in Firefox for Android

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 about:debugging in Firefox on the same machine you run web-ext from, then connect to your device from the “Setup” tab.

Further resources

This site is open source. Improve this page.