Contribute to the frontend

The Funkwhale frontend is a SPA written in Typescript and Vue.js.

Troubleshooting

Network errors (405 and 404) in the console

If you are using Google Chrome, you may have to disable the network cache:

Go to the Dev Tools
Select the Network tab
In the toolbar under the Network tab, activate the checkmark “Disable Cache”

Edits don’t appear when I check them in the browser

Reload the page with Ctrl+Shift+R (Mac: Cmd+Shift+R)

Make sure you have no add-ons in your browser that mess with the DOM. The best way to check is to open a private window/tab with Ctrl/Cmd+Shift+P (Firefox)

Data requests

Use the Vue DevTools in your browser to inspect the Rate limiter and the Data cache live and to change options such as rate limit or cached resources’ maximum age.

See the comments in the store modules for a complete feature documentation.

Cache

data.ts store - Cache and deduplicate Funkwhale objects

alt text

It is currently not possible to completely disable the cache, but you can force cache invalidation by lowering the maxAge. Whenever a frontend component requests a data object, and the cached result is older, this will force a re-fetch.

Pinia DevTools shows numberOfCachedResources and other live readonly metrics under .

To observe the changes in the cache live, slow down the rate limiter and then switch to the pinia/data/getters view in the DevTools.

Rate limiter

rateLimiter.ts store - Limit the frequency of API calls; prioritize and cancel requests

In the inia tab of VueDevTools, you find a object you can edit directly.

Disable the rate limiter to make the frontend fetch all resources the moment they are requested by any frontend component.

Increase the cooldown time to observe how requests enter and exit the queue.

Styles

<–! TODO: Mermaid diagrams –>

UI styles

graph TD
  /node_modules/bootstrap-icons/font/bootstrap-icons.css --> src/styles/font.scss
  src/styles/base/generic.scss --> src/styles/base/index.scss
  src/styles/base/index.scss --> src/styles/funkwhale.scss
  src/styles/font.scss --> src/styles/funkwhale.scss
  src/styles/colors.scss --> src/styles/funkwhale.scss
  src/styles/funkwhale.scss --> src/main.ts

App styles

graph TD
  _css_vars --> /themes/_...
  vendor/_media.scss --> _main.scss
  /globals/_... --> _main.scss
  /components/_... --> _main.scss
  /pages/_... --> _main.scss
  /themes/_... --> _main.scss
  _vars.scss --> /themes/_...

Components

Start the UI Live Docs (vitepress) and follow the link:

yarn dev:docs

Example: Button component in the live docs
Find more details about the UI library and how to contributein the live docs

Testing

Unit tests

The Funkwhale frontend contains some tests to catch errors before changes go live. The coverage is still fairly low, so we welcome any contributions.

To run the test suite, run the following command:

docker compose run --rm front yarn test:unit

To run tests as you make changes, launch the test suite with the -w flag:

docker compose run --rm front yarn test:unit -w

End-to-end testing and User testing

In addition, there are End-to-end tests (cyprus), and we are planning to do User tests in 2025.