git.r.bdr.sh - rbdr/junction/blob - README.md

   1 # Junction
   2
   3 Connect people through any URL.
   4
   5 Junction is a web extension for Firefox, Chrome and Safari that lets you start
   6 an audio call at any URL.
   7
   8 ## Building
   9
  10 Running `make` or `make package` will regenerate the content script, and
  11 package the extension for all browsers in the `./build/` directory with
  12 the following outputs:
  13
  14 - `junction.xpi`: The firefox extension
  15 - `junction.zip`: The chrome extension
  16 - `Junction.app`: The safari extension app
  17
  18 ## Developing
  19
  20 The project is divided into three main parts:
  21
  22 - `server`: A server that handles message passing to establish the WebRTC
  23   connections.
  24 - `extension`: The main code of the extension itself.
  25 - `safari`: The safari app, it wraps the extension using symlinks.
  26
  27 ### Dependencies
  28
  29 - `make` to run the build commands. It's included in `macos`
  30 - `xcode` to build the safari extension. Can be downloaded from the
  31   [apple developer portal][xcode-download].
  32 - `node` and `pnpm` to build the extension, and if you want to run the server
  33   directly. Node can be installed via brew with `brew install node`, or with
  34   a version manager like [asdf][asdf]. For `pnpm` check the [website][pnpm].
  35 - `podman` and `podman-compose` if you want to run the server as a container.
  36   Both can be installed with homebrew `brew install podman podman-compose`
  37 - `prettier` to format Javascript, JSON, Yaml, and Markdown. Will automatically
  38   install when running `make format`.
  39 - `xcbeautify` to format swift. Can be installed with homebrew
  40   `brew install xcbeautify`
  41
  42 If you're running macos and using homebrew, you can install them all with
  43 `make prepare-environment`.
  44
  45 ### Server
  46
  47 The server is a socket.io server that relays messages between peers to help
  48 establish a WebRTC connection.
  49
  50 #### Configuration
  51
  52 You can use environment variables to control the server.
  53
  54 - `JUNCTION_SERVER_PORT` which port to listen on. Defaults to `8000`.
  55
  56 ### Extension
  57
  58 The extension uses WebExtension manifest v2 and is compatible with Firefox,
  59 Chrome and Safari.
  60
  61 You can build all extensions using `make` in the root of the directory.
  62
  63 If you want to run manually then you can run `pnpm install` from the
  64 `extension` folder to install dependencies, and `pnpm build` to generate the
  65 content script.
  66
  67 ```
  68 $ pnpm install && pnpm build
  69 ```
  70
  71 #### Testing on Firefox
  72
  73 In order to test on firefox, first go to `about:debugging`, then click
  74 on the `This Firefox` option. Then click on `Load Temporary Add-On` and
  75 point the browser to the `build/junction.xpi` file if you're using `make`, or
  76 `extension/manifest.json` file if you're testing without packaging.
  77
  78 This will enable the extension and will allow you to use the inspector to
  79 debug.
  80
  81 #### Testing on Chrome
  82
  83 In order to test on chrome, first go to `chrome://extensions/`. Make sure
  84 `Developer mode` is enabled. You can drag the `build/junction.zip` file or
  85 click `Load Unpacked` and point the browser to the `extension` directory.
  86
  87 #### Testing on Safari
  88
  89 Open `Junction.app` and then enable the extension in Safari.
  90
  91 ### Formatting
  92
  93 Running `make format` will format the code with prettify and xcbeautify
  94
  95 [xcode-download]: https://developer.apple.com/xcode/resources/
  96 [asdf]: https://asdf-vm.com/
  97 [pnpm]: https://pnpm.io/installation