tildes-shepherd/DEVELOPMENT.md

Development Guide

Prerequisites

Nix + Direnv

If you have Nix with flakes enabled and Direnv installed, all you need to do is direnv allow the directory and all the prerequisites will be automatically installed. This may take a moment on first load.

Firefox and git are excluded, which are assumed to already be present on your system.

Manual

To build and develop Tildes Shepherd you will need:

• git
• NodeJS (recommended 18.16.0)
• pnpm (recommended 8.6.0)
• cargo-make
• Firefox (recommended at least 102.0)

cargo-make

All the different tasks we'd want to do are setup in Makefile.toml to be used with cargo-make (or the makers alias).

In the Tasks section below you can find a list of all the tasks, or you can look at the Makefile itself, where all the tasks have a description of what they do.

Environment

Two important environment variables are BROWSER and NODE_ENV.

BROWSER dictates what browser should be targeted, by default BROWSER="firefox". To target Chromium set BROWSER="chromium".

NODE_ENV dictates minifying and optimization found in source/build.ts, by default NODE_ENV="development" which does no minifying and includes sourcemaps in the build. Setting NODE_ENV="production" will minify and exclude sourcemaps.

Tasks

Click to view all tasks

• The most common scenario will likely be that you want a live-reloading browser instance, this can be done using the dev task.

# If makers doesn't work, replace it with cargo-make.
makers dev

# To change the environment, prefix the command with the
# variables you want to set.
BROWSER="chromium" NODE_ENV="production" makers dev

• To watch for changes but without starting a live-reloading browser instance, use the watch task.

makers watch

# Which is a simple alias for the following.
WATCH="true" makers build

• To start a browser instance with an already built extension present in the build/ directory, the run task is available. Note that this will fail if the extension hasn't been built before.

makers run

• To clean the build directory, a clean task is available. This uses trash-cli so if you accidentally remove something and want it back, check your trash bin where you can restore it.

makers clean

# Clean the Chromium directory.
BROWSER="chromium" makers clean

• To lint the code, lint is the task.

makers lint

# To only lint JS or SCSS.
makers lint-js
makers lint-scss

• To pack the WebExtension for publishing, pack is what you need.

# Make sure to set NODE_ENV, otherwise the extension size will be
# a lot bigger than it needs to be.
NODE_ENV="production" makers pack

# To pack Chromium.
BROWSER="chromium" NODE_ENV="production" makers pack

• Mozilla Addons requires the zipped source code too, since we're using minification, so zip-source is available. This uses Git's archive command.

makers zip-source