Vue.js Usage Guidelines

This document describes how Vue.js is used and structured in this frontend project. The goal is to keep the codebase predictable, maintainable, and easy to scale, while sharing common conventions across the team.

1. Component-Based Architecture

The core concept of Vue.js in this project is component-based development. The application is built by composing small, focused components together.

Props and Slots

Components communicate primarily through props and slots when needed.
Props are documented here: https://vuejs.org/guide/components/props.html
Slots are documented here: https://vuejs.org/guide/components/slots.html

⚠️ Guideline: even if it is not always perfectly enforced, we try to limit prop drilling to a maximum of 3 component levels. If data needs to travel deeper or across distant components, other patterns (composables or store) should be considered.

Reactivity with `ref()`

To make component state reactive, this project intentionally uses ref() by default.

Documentation: https://vuejs.org/api/reactivity-core.html#ref

Although Vue also provides reactive(), it is not commonly used in this project.

Reasons:

ref() has fewer implicit side effects
It behaves more predictably with destructuring
It reduces reactivity-related bugs in complex components

const isOpen = ref(false)
const items = ref<Item[]>([])

Derived State with `computed`

We use computed properties whenever a value is derived from other reactive values.

Documentation: https://vuejs.org/guide/essentials/computed.html

const total = computed(() => price.value * quantity.value)

Benefits:

Declarative and readable
Automatically cached
Keeps templates clean

`watch` and `watchEffect` (Use with Caution)

watch: https://vuejs.org/api/reactivity-core.html#watch
watchEffect: https://vuejs.org/api/reactivity-core.html#watcheffect

⚠️ Warning: watch and watchEffect are present in the project but we try to use them only when necessary.

Why?

They force reactivity
They can introduce side effects
They make data flow harder to reason about

If a value can be expressed declaratively, computed is always preferred over watch.

2. Global State Management with Pinia

This project uses Pinia as its state management solution.

Documentation: https://pinia.vuejs.org/

What is a Store?

A store is a centralized place to manage shared state that needs to be accessed across multiple components or pages.

We use the store only when needed, typically when:

Data must persist across page navigation
The same information is reused in multiple, distant parts of the application

Examples in this project:

/config information
Global notifications

The goal is to avoid unnecessary global state while keeping shared data consistent.

3. Composables

Composables are a key part of the architecture.

Documentation: https://vuejs.org/guide/reusability/composables.html

What is a Composable?

A composable is a function that encapsulates reactive logic tied to Vue using the Composition API (ref, computed, watch, lifecycle hooks, etc.).

How We Use Composables

In this project, composables are mainly used to:

Share and reuse logic across multiple components
Manage state or behavior within a specific domain of the application

Example:

The upload domain contains many components at different nesting levels
These components rely on shared reactive values and logic
A composable centralizes this logic and avoids deep prop drilling

Composables vs Utils

We clearly distinguish composables from utils:

Composable → reactive logic tied to Vue
Util → pure function, independent of Vue

Concept	Depends on Vue	Reactive	Usage
Composable	✅	✅	UI / domain logic
Util	❌	❌	Pure business or helper logic

This separation helps keep the codebase modular, testable, and easy to reason about.

4. Keycloak

For the IGN instance, Keycloak is used as SSO Authentication service. The Keycloak instance used by IGN relies on a custom theme (panoramax) with specific wording and custom CSS.

Sometimes, during updates, the Keycloak theme of the IGN instance reverts to the default theme. When this happens, you need to reselect the “panoramax” theme in the Keycloak admin console: select the “geovisio” realm → Realm Settings → Themes.

Note

Sometimes, during Keycloak updates or deployments, the theme disappears from the list of selectable themes. In that case, you need to redeploy the master branch to production (sometimes multiple times).

5. Additional Technologies Used

This project also relies on the following tools and libraries:

TypeScript

Used for static typing and safer code
Documentation: https://www.typescriptlang.org/docs/

vue-i18n

Used for internationalization and translations
Documentation: https://vue-i18n.intlify.dev/
To add a translate locale see the documentation here

Axios

Used for HTTP requests and API communication
Documentation: https://axios-http.com/

Bootstrap Icons

Used for icons across the UI
Documentation: https://icons.getbootstrap.com/

Final Notes

These guidelines are not meant to be overly restrictive but to provide a shared mental model for how Vue.js is used in this project.

Consistency, predictability, and clarity are preferred over clever abstractions.