funkwhale/front/ui-docs/using-components.md

Using Components

We distinguish between components that are coupled with funkwhale-specific datatypes and "pure" user interface components:

• Funkwhale-specific components such as Activity or AlbumCard import from types.ts.
• Pure Ui components (found in src/components/ui) are independent from Funkwhale. Think of Button, Tabs or Layout

---

toc

Anatomy of a component file

Imports

First, import vue features and external libraries. Add the sub-components you want to use last. Order each block of imports by alphabet to prevent commit diff noise.

Script

Add a blank line between Imports and script. Use modern typescript-friendly features such as defineModel and defineProps as documented in the Vue Docs instead of Macros.

Template

If you are new to Vue, read the docs, especially the chapter about Single-File Components, to get familiar.

Style

Don't pollute the global namespace. Funkwhale compiles a single stylesheet (used in the app, the blog and the website). If you need specific styles in your component, use vue's SFC features such as module. Vue will give you a $style object containing all locally defined classes.

<script setup>
import { ref } from "vue";
const theme = ref({
  color: "red",
});
</script>

<style module>
.content {
  color: v-bind("theme.color");
}
</style>

<template>
  <div :class="$style.content"></div>
</template>

::: details Tip: Debugging styles

We have enabled the vite feature css.devSourcemap: true so that in your browser devtools, you can trace the code responsible for module styles:

:::

::: info What about the global style?

As of now, class and variable names from the global styles are not available as typescript objects. We should definitely add this feature at some point.

:::

Using Ui components in your views

<script setup>
import Alert from "~/components/ui/Alert.vue";
import Button from "~/components/ui/Button.vue";
</script>

<style module></style>

<template>
  <Alert />
  <Button />
</template>