Stump Docs

If you're interested in supporting Stump's development, and you know how to code, follow the steps outlined in the developer guide for information about setting up your development environment. If you want to improve Stump's language support, visit the Weblate project page here.

Developer Guide

Contributions are very encouraged and welcome! Be sure to review the CONTRIBUTING.md before getting started with your contribution.

If you're completely new to rust and/or web development, I put together a small set of resources to get you started with Stump.

Ensure you are on the nightly branch before continuing.

If you are on a Windows machine, you will need Visual C++ installed on your system.

If you are on a Mac with Apple Silicon, you will need to install Rosetta.

You need to install yarn, rust, and node. Additionally, if you want to run any of the dev scripts on the rust side of things, you'll need to install bacon. Afterwards, run the following:

yarn run setup

Running Stump

I use yarn workspaces and cargo workspaces:

# run the webapp + server
yarn dev:web
# run the desktop app + server
yarn start:desktop
# run the docs website
yarn docs dev

Or cargo for the server:

cargo run --package stump_server --bin stump_server

Database

Stump uses SQLite by default and no database setup is required to get started. PostgreSQL is also experimentally supported. A quick command to get a local instance up for development could be (assuming you have Docker installed):

docker run -d \
  --name stump-postgres-dev \
  -e POSTGRES_USER=stump \
  -e POSTGRES_PASSWORD=stump \
  -e POSTGRES_DB=stump \
  -p 5432:5432 \
  postgres:16-alpine

Then run the server with the STUMP_DATABASE_URL env var pointing at it:

STUMP_DATABASE_URL=postgresql://stump:stump@localhost:5432/stump \
cargo run --package stump_server --bin stump_server

When you're done:

docker rm -f stump-postgres-dev

GraphQL

If you plan to update or add any GraphQL queries or mutations, you'll likely want to keep a process running to watch for changes and automatically generate the TypeScript types. You can do this by running the following in the packages/graphql directory:

yarn graphql-codegen --watch

Notes and Tips

Stump has gotten quite large and complex, so I've put together a few notes and tips to help you get started.

Where to start?

If you aren't sure what to work on, I recommend taking a look at some of the open issues on GitHub. You can also reach out to me on Discord, or an open GitHub issue, if you have any questions.

In general, some good places to start might be:

Translations via Weblate, so Stump is accessible to as many people as possible
Writing comprehensive tests
Improving the UI/UX, even small changes can go a long way
CI pipelines, automated release processes, and other devops-related efforts
Addressing TODO or FIXME comments in the codebase

Code Style, Formatting, and Linting

Stump is developed using primarily Rust and TypeScript.

For Rust, I use rustfmt for formatting, and clippy for linting. For TypeScript, I use Prettier for formatting, and ESLint for linting. While I definitely recommend using these tools as you develop, there is a pre-commit hook that will lint and format your code before committing.

I also want to point out that this repository uses 4 tab spaces for indentation. This is primarily for accessibility, as well as to be consistent with the Rust codebase. If you'd like, you can configure your editor to render whatever indentation you prefer, even though the raw code will be as described above. I personally maintain the 4 tab space rendering on the Rust side and shorten it to only render 2 on the frontend side.

Component Library

Stump has a custom component library used throughout the browser package (the web UI and desktop app). This library can be found at packages/components, and was developed with Storybook in mind. For getting started building out designs and components in Stump, I highly recommend going through the stories available in the Storybook UI:

yarn storybook

This will give you a good idea of what components are available and how they can be used.

Testing

This is an area that I would like to improve and is very challenging to action on because testing can be quite the slog. There are a few different flavors of testing that exist today that provide a solid foundation but could use development to improve coverage and reliability.

TypeScript unit tests (Vitest)

The majority of the frontend packages/apps use Vitest for unit and component tests. Run them from each package:

yarn workspace @stump/browser test
yarn workspace @stump/sdk test
yarn workspace @stump/expo test

Or just run all of them at once:

yarn test

These tests are meant to be more isolated and focused on testing the logic of a single component or function. So if something requires 100s of lines of mocking code to set up or requires a running server, it is likely not a good candidate for this suite

e2e tests (Playwright)

Browser end-to-end tests live in apps/web/tests/ and run against a live Stump server:

# one-time browser install
yarn workspace @stump/web e2e:install
# run tests (requires a running server on port 10801)
yarn workspace @stump/web e2e

This suite uses two different types of test users:

A "persona" that is meant to be more of a catch-all user for testing common flows
An ephemeral user that is created to test a specific flow that doesn't require a persistent user at the start of a run

Generally speaking what I would like to use this suite for is to test the full stack of Stump where unit tests aren't sufficient. Things like multi-step forms that change server state, flows that require coordinated frontend and backend validation, etc.

Rust server integration tests

apps/server/tests/ contains integration tests that spin up a server instance and test the API:

cargo test --package stump_server --test api_tests

Anything that requires a running server and database to fully test is a good candidate for this suite. It uses a lot of fake_data to insert data into the in-memory database.

Rust unit tests

Unit tests for core logic live inline in the relevant crate using the standard conventions:

cargo test

Things like validation, pure functions, and other logic that can be tested without a running server are good candidates for this suite.

Contributing