102 lines
3.1 KiB
Markdown
102 lines
3.1 KiB
Markdown
|
# Development Guide
|
||
|
|
|
||
|
|
## Prerequisites
|
||
|
|
|
||
|
|
### Nix + Direnv
|
||
|
|
|
||
|
|
If you have [Nix](https://nixos.org/) with flakes enabled and [Direnv](https://direnv.net/) 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](https://git-scm.com)
|
||
|
|
* [NodeJS](https://nodejs.org) (recommended 18.16.0)
|
||
|
|
* [pnpm](https://pnpm.io) (recommended 8.6.0)
|
||
|
|
* [cargo-make](https://sagiegurari.github.io/cargo-make/)
|
||
|
|
* [Firefox](https://mozilla.org/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
|
||
|
|
|
||
|
|
<details>
|
||
|
|
<summary>Click to view all tasks</summary>
|
||
|
|
|
||
|
|
* The most common scenario will likely be that you want a live-reloading browser instance, this can be done using the `dev` task.
|
||
|
|
|
||
|
|
```sh
|
||
|
|
# 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.
|
||
|
|
|
||
|
|
```sh
|
||
|
|
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.
|
||
|
|
|
||
|
|
```sh
|
||
|
|
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.
|
||
|
|
|
||
|
|
```sh
|
||
|
|
makers clean
|
||
|
|
|
||
|
|
# Clean the Chromium directory.
|
||
|
|
BROWSER="chromium" makers clean
|
||
|
|
```
|
||
|
|
|
||
|
|
* To lint the code, `lint` is the task.
|
||
|
|
|
||
|
|
```sh
|
||
|
|
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.
|
||
|
|
|
||
|
|
```sh
|
||
|
|
# 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.
|
||
|
|
|
||
|
|
```sh
|
||
|
|
makers zip-source
|
||
|
|
```
|
||
|
|
</details>
|