Sage

Contributing

It is recommended to use the Nix development shell instructions to have access to all repository tooling, but the core application can be developed without this. Here are the simple instructions to begin:

1. (optional) if bun is not provided by nix, install bun first
2. bun install to install all javascript dependencies
3. bun run dev -- --open to begin developing with hot reload, which will auto-open the app in the browser

Tools

1. typescript as scripting language
2. sveltekit as full-stack application framework
3. svelte as component framework
4. vite as javascript module bundler
5. bun as server runtime and package manager
6. xyflow as flowchart component library
7. tailwind as component styling framework
8. shadcn-svelte as component repository
9. playwright as end-to-end testing framework
10. vitest as unit testing framework
11. svelte-persisted-store as temporary(!) data storage layer
12. quill or TipTap as WYSIWYG editor component
13. renovate as dependency automation tool
14. elkjs as flowchart layout algorithm

Nix development shell

As with many of @schradert's code repositories, this one uses the nix: package manager as a metatool for accessing, building, and running any other software reproducibly. To access the tools in this section (required for final approval on merging pull requests into trunk), please follow the instructions below.

Installing Nix

1. Follow the installation instructions for your runtime preference.
2. Activate necessary experimental features

mkdir -p ~/.config/nix
echo "experimental-features = nix-command flakes" >> ~/.config/nix/nix.conf

What this does is allow you to use the nix command directly on a "flake", which are essentially standard nowadays

Activating the development environment

Because the nix-command and flakes features are active now, simply run nix develop from within the project directory and watch the magic happen. This will take a while to complete but by the end, you will enter an interactive shell with all of the tools you need to work on the project.

This development environment is configurable from within the project, but it does not hot reload by default without a separate tool: direnv. To enable this autoloading feature, install the necessary tools like so:

nix profile install nixpkgs#direnv nixpkgs#nix-direnv

direnv is a simple but effective tool that will run code in every .envrc in an entered directory and its ancestors. We include the nix-direnv library to support building the project's development shell using Nix.

After running this command, a prompt will instruct you to allow the project's environment to evaluate by running direnv allow. Now any process that enters any of this project's directories will be sure to operate within the development environment.

If there are issues with code not autoloading, direnv reload will force the environment to reevaluate.

Nix Tooling

1. canivete as repository framework
2. pre-commit as git hook framework
3. commitizen as release management tool
4. gitleaks as secret exposure prevention tool
5. lychee as hyperlink validator
6. markdownlint as markdown linter
7. mdsh as markdown shell preprocessor
8. tagref as code annotation framework
9. typos as spell checker
10. alejandra as nix formatter
11. deadnix as nix linter for dead code
12. statix as general nix linter
13. biome as javascript linter and formatter