Modułowe zarządzanie stanem w Vue.js: dobre praktyki skalowalnej i łatwej w utrzymaniu konfiguracji store’a

Od redakcji: Ten artykuł został pierwotnie napisany i opublikowany w grudniu 2024 roku. W październiku 2026 roku został przejrzany i zaktualizowany tak, aby uwzględniał aktualne wersje Pinia, Vuex i Nuxt.

Modułowe zarządzanie stanem w Vue.js polega na podzieleniu współdzielonego stanu aplikacji na małe store’y skupione wokół konkretnych funkcji, zamiast trzymać wszystko w jednym dużym globalnym store’ze. W tworzeniu aplikacji Vue.js sposób zarządzania stanem, czyli to, jak przechowujesz, udostępniasz i aktualizujesz dane, decyduje o tym, czy rosnąca baza kodu pozostanie przejrzysta, szybka i skalowalna, czy zamieni się w plątaninę powiązanych ze sobą komponentów.

Jak podaje dokumentacja Vue, każda instancja komponentu Vue sama już „zarządza” własnym reaktywnym stanem. To samodzielna jednostka składająca się z następujących elementów:

1. Stan, czyli źródło prawdy, które napędza naszą aplikację;

2. Widok, czyli deklaratywne odwzorowanie stanu;

3. Akcje, czyli możliwe sposoby zmiany stanu w reakcji na działania użytkownika w widoku.

Poniżej znajdziesz prostą ilustrację koncepcji „jednokierunkowego przepływu danych”:

Źródło grafiki: www.vuejs.org

Ta prostota zaczyna się jednak załamywać, gdy wiele komponentów współdzieli ten sam stan:

• Wiele widoków może zależeć od tego samego fragmentu stanu.

• Akcje z różnych widoków mogą wymagać modyfikacji tego samego fragmentu stanu.

Aby rozwiązać ten problem, możesz skorzystać z narzędzi do zarządzania stanem, takich jak Vuex czy Pinia, ale żeby używać ich naprawdę skutecznie, warto zastosować podejście modułowego zarządzania stanem.

W tym artykule wyjaśnimy, czym jest zarządzanie stanem w Vue.js, i przyjrzymy się bliżej modułowej architekturze w Vue.js oraz narzędziom i technikom, które pomagają skutecznie ją wdrożyć. Od podstawowych pojęć po instrukcje krok po kroku z użyciem popularnych narzędzi, pokażemy ci, jak uporządkować stan tak, by maksymalnie ułatwić utrzymanie aplikacji. Po drodze omówimy też częste pułapki, dobre praktyki zarządzania stanem w Vue.js oraz bardziej zaawansowane zastosowania, takie jak optymalizacja wydajności i moduły ładowane dynamicznie.

Czym jest modułowe zarządzanie stanem w Vue.js i dlaczego ma znaczenie?

Modułowe zarządzanie stanem porządkuje stan aplikacji, dzieląc go na mniejsze, samodzielne moduły, z których każdy odpowiada za konkretny fragment danych i logiki aplikacji. Takie podejście poprawia organizację kodu, skalowalność i łatwość utrzymania, bo pozwala programistom niezależnie pracować nad odizolowanymi modułami, a jednocześnie zachować przejrzystą i uporządkowaną architekturę stanu.

Szerzej patrząc, zarządzanie stanem w Vue.js to proces organizowania i kontrolowania współdzielonego stanu, czyli danych aplikacji, w wielu komponentach. Każdy komponent ma własny stan lokalny, ale wraz z rozwojem aplikacji zarządzanie danymi, które trzeba współdzielić między komponentami, staje się coraz bardziej złożone. Narzędzia takie jak Vuex czy Pinia wspierają modułowe zarządzanie stanem w Vue, ułatwiając debugowanie, współpracę zespołową oraz dynamiczne ładowanie i ponowne wykorzystywanie modułów stanu wtedy, gdy są potrzebne.

W większych aplikacjach, gdzie zarządzanie całym stanem w jednym miejscu staje się nieporęczne, priorytetem staje się podział na mniejsze jednostki, czyli moduły, zamiast jednego scentralizowanego store’a. Oto kilka powodów:

1. Skalowalność: Dzielenie stanu na logiczne części ułatwia zarządzanie nim wraz z rozwojem aplikacji.

2. Ponowne wykorzystanie: Moduły można wykorzystywać w różnych częściach aplikacji, a nawet w innych projektach.

3. Lepsza organizacja: Każdy moduł skupia się na konkretnej funkcji albo obszarze, na przykład uwierzytelnianiu, produktach czy koszyku, dzięki czemu kod pozostaje czysty i łatwy w utrzymaniu.

4. Rozdzielenie odpowiedzialności: Każdy moduł może niezależnie obsługiwać swój stan, mutacje, akcje i gettery.

5. Lepsza utrzymywalność: Łatwiej zlokalizować i naprawić problemy w konkretnych częściach aplikacji.

6. Niezależny rozwój: Zespoły mogą pracować nad różnymi modułami bez wchodzenia sobie w drogę.

7. Lepsze testowanie: Moduły można testować osobno.

8. Łatwiejsze skalowanie: Dodawanie nowych funkcji jest prostsze, gdy tworzysz nowe moduły, zamiast modyfikować monolityczny store.

Modułowe zarządzanie stanem jest kluczowe przy budowaniu skalowalnych i łatwych w utrzymaniu aplikacji Vue, zwłaszcza gdy rośnie ich złożoność. Stosując opisane niżej dobre praktyki, programiści mogą utrzymać stan w porządku, zadbać o jego utrzymywalność i przygotować aplikację na przyszłe zmiany.

Vuex czy Pinia: którą bibliotekę do zarządzania stanem wybrać w Vue.js?

Właściwy wybór zależy od rozmiaru aplikacji, jej złożoności i długoterminowych potrzeb. W produkcyjnych projektach Vue najczęściej korzysta się z dwóch rozwiązań do obsługi stanu: Vuex i Pinia. W nowych projektach opartych na Vue 3 oficjalnie rekomendowanym wyborem jest Pinia, natomiast Vuex pozostaje solidną opcją dla zespołów, które już z niego korzystają. Oto najważniejsze różnice w skrócie:

Jak Vuex zarządza stanem w Vue.js?

Vuex to biblioteka do zarządzania stanem w aplikacjach Vue.js, stworzona po to, by centralizować współdzielony stan i zarządzać nim w różnych komponentach. Opiera się na wzorcu jednokierunkowego przepływu danych i jest głęboko zintegrowana z Vue, dzięki czemu łatwo śledzić zmiany stanu w przewidywalny sposób.

Vuex jest szczególnie przydatny w średnich i dużych aplikacjach, w których wiele komponentów musi współdzielić dane i utrzymywać je w synchronizacji. Warto znać kilka podstawowych pojęć związanych z Vuex:

• State: Jedyne źródło prawdy w Vuex. Przechowuje współdzielone dane aplikacji i udostępnia je wszystkim komponentom.

• Getters: Podobnie jak computed properties w Vue, służą do wyprowadzania lub filtrowania danych ze stanu.

• Mutations: Jedyny sposób na zmianę stanu w Vuex. Mutacje są synchroniczne i pozwalają Vue DevTools śledzić zmiany stanu.

• Actions: Służą do operacji asynchronicznych, takich jak wywołania API, zanim zatwierdzą mutacje zmieniające stan.

• Modules: Vuex pozwala podzielić store na mniejsze, modułowe części dla lepszej organizacji, zwłaszcza w dużych aplikacjach.

Vuex działa w następujący sposób:

• Scentralizowany store: Vuex korzysta z jednego store’a do zarządzania całym stanem aplikacji, dzięki czemu dane pozostają spójne we wszystkich komponentach.

• Interakcja z komponentami: Komponenty mogą odczytywać stan, dispatchować akcje i commitować mutacje przez store Vuex.

• Jednokierunkowy przepływ danych: Stan przepływa ze store’a do komponentów, a komponenty mogą go aktualizować wyłącznie przez mutacje, co sprawia, że cały przepływ jest przewidywalny i łatwiejszy do debugowania.

Architekturę Vuex dobrze pokazuje poniższy schemat:

Źródło grafiki: www.vuejs.org/guide/

Aby użyć Vuex w projekcie, najpierw musisz zdefiniować store. Oto podstawowy store ze stanem, getterem, mutacją i akcją:

// store/index.js
import { createStore } from 'vuex';

export const store = createStore({
  state: {
    count: 0,
  },
  getters: {
    doubleCount: (state) => state.count * 2,
  },
  mutations: {
    increment(state) {
      state.count++;
    },
  },
  actions: {
    incrementAsync({ commit }) {
      setTimeout(() => {
        commit('increment');
      }, 1000);
    },
  },
});

Następnie użyj go w komponencie lub na stronie Vue:

<template>
  <div>
    <p>Count: {{ $store.state.count }}</p>
    <p>Double Count: {{ $store.getters.doubleCount }}</p>
    <button @click="$store.commit('increment')">Increment</button>
    <button @click="$store.dispatch('incrementAsync')">Increment Async</button>
  </div>
</template>

<script>
export default {
  name: "CounterComponent",
};
</script>

W poniższej instrukcji krok po kroku zobaczysz, jak podzielić taki store na moduły związane z konkretnymi funkcjami, aby uzyskać skalowalną konfigurację store’a w Vue.

Wraz z rozwojem Vue 3 i nowszych narzędzi, takich jak Pinia, ponownie oceniono poziom złożoności Vuex. Choć Vuex nadal jest rozbudowany i szeroko używany, wielu programistów wybiera dziś Pinia ze względu na prostotę i nowoczesne API. Mimo to Vuex wciąż pozostaje solidnym wyborem dla zespołów, które już go dobrze znają, albo dla aplikacji z bazą kodu legacy.

Dlaczego Pinia jest rekomendowanym rozwiązaniem do zarządzania stanem w Vue 3?

Pinia to nowoczesna, lekka biblioteka do zarządzania stanem w Vue.js i oficjalnie rekomendowane rozwiązanie do zarządzania stanem w Vue. Zapewnia przejrzysty i wydajny sposób zarządzania stanem aplikacji oraz współdzielenia go między komponentami. Pinia powstała po to, by rozwiązać część ograniczeń i złożoności znanych z Vuex, oferując prostsze i bardziej intuicyjne API, a jednocześnie wspierając zaawansowane możliwości, takie jak:

• Prostsze API: Składnia jest bardziej bezpośrednia niż w Vuex, co ułatwia modułową konfigurację store’a. Stan, gettery i akcje są opisane w jeden spójny sposób.

• Przyjazność dla Composition API: Pełna zgodność z Composition API w Vue 3 sprawia, że Pinia łatwiej wykorzystać w nowoczesnych aplikacjach Vue. Od wersji Pinia v3 biblioteka obsługuje wyłącznie Vue 3; projekty oparte na Vue 2 mogą nadal korzystać z Pinia v2.

• Integracja z DevTools: Możliwości debugowania i inspekcji oferowane przez Vue DevTools ułatwiają śledzenie i zarządzanie stanem aplikacji.

• Modułowe store’y: Zamiast jednego scentralizowanego store’a, jak w Vuex, Pinia wspiera modułowe store’y, dzięki czemu możesz podzielić stan na mniejsze i łatwiejsze do opanowania części.

• Wsparcie dla TypeScript: Bezpieczeństwo typów i autouzupełnianie od razu po uruchomieniu.

• Wsparcie dla SSR: Działa bezproblemowo z frameworkami renderowanymi po stronie serwera, czyli frameworkami takimi jak Nuxt.

• Brak mutacji: W przeciwieństwie do Vuex, Pinia nie korzysta z mutacji, dzięki czemu aktualizowanie stanu jest prostsze, bo odbywa się bezpośrednio przez akcje.

Pinia opiera się na kilku podstawowych pojęciach, które sprawiają, że zarządzanie stanem aplikacji jest intuicyjne i wydajne:

• State: Definiuje reaktywne dane, które przechowują stan aplikacji i nim zarządzają.

• Getters: Podobnie jak computed properties, służą do wyprowadzania lub obliczania danych na podstawie stanu.

• Actions: Metody służące do modyfikowania stanu albo obsługi zadań asynchronicznych, takich jak wywołania API.

Aby użyć Pinia w projekcie, najpierw musisz zdefiniować store:

// stores/counter.js
import { defineStore } from 'pinia';

export const useCounterStore = defineStore('counter', {
  state: () => ({
    count: 0,
  }),
  getters: {
    doubleCount: (state) => state.count * 2,
  },
  actions: {
    increment() {
      this.count++;
    },
  },
});

Następnie możesz użyć tego store’a w komponencie lub na stronie Vue w następujący sposób:

<script setup>
import { useCounterStore } from './stores/counter';

const counter = useCounterStore();
</script>

<template>
  <div>
    <p>Count: {{ counter.count }}</p>
    <p>Double Count: {{ counter.doubleCount }}</p>
    <button @click="counter.increment">Increment</button>
  </div>
</template>

Pinia to świetny wybór do zarządzania stanem w aplikacjach Vue, a przy tym upraszcza tworzenie modułowego store’a w Vue.js. Łączy prostotę, duże możliwości i rozwiązania przyjazne programistom, dlatego jest szczególnie polecana w projektach opartych na Vue 3.

Jak wdrożyć modułowe zarządzanie stanem w Vue.js: instrukcja krok po kroku

Ta część składa się z dwóch sekcji. W pierwszej pokażemy, jak wdrożyć modułowe zarządzanie stanem w Vuex, a w drugiej przejdziemy przez ten sam proces z użyciem Pinia.

Jak utworzyć modułowy store z użyciem modułów Vuex

Vuex obsługuje moduły za pomocą właściwości modules. Każdy moduł jest samodzielny i ma własny stan, mutacje, akcje oraz gettery.

Najpierw utwórzmy modułowy store o nazwie auth.js. Aby wdrożyć modułową architekturę Vuex, włącz właściwość namespaced w modułach, żeby lepiej je odseparować. Na przykład:

// store/modules/auth.js
export default {
  namespaced: true,
  state: {
    user: null,
  },
  mutations: {
    setUser(state, user) {
      state.user = user;
    },
  },
  actions: {
    login({ commit }, user) {
      commit('setUser', user);
    },
  },
};

A teraz cart.js:

// store/modules/cart.js
export default {
  namespaced: true,
  state: {
    items: [],
  },
  mutations: {
    addItem(state, item) {
      state.items.push(item);
    },
  },
};

Następnie zaimportujmy je do globalnego store’a:

// store/index.js
import { createStore } from 'vuex';
import auth from './modules/auth';
import cart from './modules/cart';

export default createStore({
  modules: {
    auth,
    cart,
  },
});

Na koniec, aby użyć ich w komponentach lub na stronach Vue, możemy zrobić to tak:

<template>
  <div>
    <p>User: {{ user }}</p>
    <p>Cart Items: {{ cartItems.length }}</p>
  </div>
</template>

<script>
import { mapState } from 'vuex';

export default {
  computed: {
    ...mapState('auth', ['user']),
    ...mapState('cart', { cartItems: 'items' }),
  },
};
</script>

I właśnie tak możesz wdrożyć modułowe zarządzanie stanem w Vue z użyciem Vuex. Teraz zobaczmy, jak zrobić to samo w Pinia.

Jak tworzyć modułowe store’y w Pinia

Pinia wspiera modułowe store’y z założenia. Każdy store definiuje się niezależnie za pomocą defineStore, co ułatwia zarządzanie nim.

Najpierw utwórzmy modułowy store o nazwie auth.js:

// stores/auth.js
import { defineStore } from 'pinia';

export const useAuthStore = defineStore('auth', {
  state: () => ({
    user: null,
  }),
  actions: {
    login(user) {
      this.user = user;
    },
    logout() {
      this.user = null;
    },
  },
});

A teraz cart.js:

// stores/cart.js
import { defineStore } from 'pinia';

export const useCartStore = defineStore('cart', {
  state: () => ({
    items: [],
  }),
  actions: {
    addItem(item) {
      this.items.push(item);
    },
    removeItem(index) {
      this.items.splice(index, 1);
    },
  },
});

W przeciwieństwie do Vuex nie musimy importować tych modułowych store’ów do globalnego store’a. Zamiast tego możemy używać ich bezpośrednio w komponentach lub na stronach Vue:

<script setup>
import { useAuthStore } from './stores/auth';
import { useCartStore } from './stores/cart';

const auth = useAuthStore();
const cart = useCartStore();
</script>

<template>
  <div>
    <p>User: {{ auth.user }}</p>
    <p>Cart Items: {{ cart.items.length }}</p>
  </div>
</template>

I tak właśnie możesz używać Pinia do wdrożenia modułowego zarządzania stanem. Jest ono wyraźnie łatwiejsze w użyciu i zrozumieniu, a przy tym zapewnia bardzo podobną funkcjonalność. Takie podejście wyraźnie ogranicza ilość boilerplate’u i sprzyja czystszemu oraz łatwiejszemu w utrzymaniu zarządzaniu stanem w Vue.

Jakie są dobre praktyki modułowego zarządzania stanem w Vue.js?

Przy wdrażaniu modułowego zarządzania stanem w projekcie Vue lub Nuxt warto pamiętać o kilku dobrych praktykach:

• Skup się na jednej odpowiedzialności: Zadbaj o to, by każdy moduł odpowiadał za jedną odpowiedzialność albo konkretny obszar funkcjonalny. Dzięki temu moduły są spójne i przewidywalne, co ułatwia ich utrzymanie.

• W projektach Vue 3 stawiaj na Pinia: Jeśli korzystasz z Vue 3, Pinia powinna być pierwszym wyborem ze względu na czystsze i bardziej intuicyjne API. Jej nowoczesna konstrukcja upraszcza modułowe zarządzanie stanem i ogranicza ilość boilerplate’u.

• Używaj namespacingu w Vuex: Jeśli pracujesz z Vuex, zawsze włączaj namespacing w modułach. Dzięki temu unikniesz konfliktów nazw, wyraźnie oddzielisz granice modułów i łatwiej zarejestrujesz moduły dynamicznie.

• Utrzymuj stan w lekkiej, modułowej formie: Nie przeciążaj stanu. Dziel go na logiczne części, by zachować przejrzystość, łatwość utrzymania i skalowalność.

• Wspieraj ponowne wykorzystanie: Twórz moduły wielokrotnego użytku ze współdzieloną logiką, żeby ograniczać powielanie. To nie tylko oszczędza czas tworzenia oprogramowania, ale też ułatwia dostosowanie aplikacji do zmieniających się wymagań.

• Dokumentuj zależności między modułami: Jeśli moduły muszą ze sobą współpracować, dokładnie dokumentuj ich zależności i sposób komunikacji. To zwiększa przejrzystość, ogranicza ryzyko błędów i ułatwia debugowanie całemu zespołowi.

Stosowanie tych praktyk przekłada się na wyższą jakość rozwiązania, a także większą stabilność i łatwość utrzymania.

Jak uporządkować aplikację Nuxt z modułami i Pinia

Kilka lat temu napisałem artykuł o wykorzystaniu modułów i Pinia do uporządkowania aplikacji Nuxt, tak aby była bardziej rozszerzalna i skalowalna. Będzie on punktem wyjścia dla tego rozdziału. Ten przykład zakłada, że masz zainstalowany moduł @pinia/nuxt.

Po wygenerowaniu prostej aplikacji Hello World w Nuxt zastąpmy zawartość strony app.vue poniższym kodem:

<template>
  <div>
    <NuxtPage/>
  </div>
</template>

Dzięki temu zostanie wyrenderowana strona utworzona w naszym module.

Następnie utwórzmy prosty komponent BlogPost.vue, który wyświetla prosty tekst przekazany do niego przez prop:

<script setup lang="ts">
const props = defineProps({
  blog: {
    type: String,
    required: true
  }
})
</script>

<template>
  <div>
    {{ blog }}
  </div>
</template>

Następnie utworzymy modułowy store Pinia, który będzie przechowywał informacje o naszym blogu:

// modules/blog/stores/store.ts

export const useBlogStore = defineStore('blog-store', {
  state: () => ({
    value: 1
  }),

  getters: {
    valueWithName: state => `Value is ${state.value}`
  },

  actions: {
    setNewValue(newValue: number) {
      this.value = newValue
    }
  }
})

Następnie utwórzmy stronę, która renderuje komponent BlogPost.vue oraz informacje przechowywane w store’ze:

<script setup lang="ts">
const { currentRoute } = useRouter()
const blogStore = useBlogStore()
</script>

<template>
  <section>
    <BlogPost :blog="`Test blog post ${currentRoute.params.id}`"/>
    <span>Current value from blogStore: {{ blogStore.value }}</span>
  </section>
</template>

Na koniec zamknijmy to wszystko w module Nuxt:

import {
  defineNuxtModule,
  createResolver,
  addImportsDir,
} from '@nuxt/kit'

export default defineNuxtModule({
  name: 'blog-module',
  setup () {
    const { resolve } = createResolver(import.meta.url)

    addImportsDir(resolve('components'))
    addImportsDir(resolve('pages'))

    // Register the module's Pinia stores for auto-import
    addImportsDir(resolve('stores'))
  }
})

Ponieważ moduł rejestruje swoje katalogi do automatycznego importu, możemy korzystać z nich w projekcie głównym. Domyślnie @pinia/nuxt automatycznie importuje store’y tylko z folderu stores samej aplikacji (app/stores w Nuxt 4), dlatego store’y znajdujące się wewnątrz modułu trzeba zarejestrować w ten sposób. Połączenie Pinia z modułową architekturą Nuxt pozwala tworzyć skalowalne konfiguracje store’ów Vue: definiujesz moduły w formacie zgodnym z Nuxt i automatycznie importujesz je do projektu, co upraszcza konfigurację.

Zadbaj o przyszłość swoich aplikacji Vue dzięki modułowemu zarządzaniu stanem

Modułowe zarządzanie stanem to podstawa, jeśli chcesz skalować zarządzanie stanem w Vue.js. Dzięki niemu aplikacje są też łatwiejsze w utrzymaniu, gdy rośnie ich złożoność. Wprowadza do bazy kodu przejrzystość, strukturę i elastyczność, a to pozwala sprawnie zarządzać stanem aplikacji i dobrze go organizować.

Choć zarówno Vuex, jak i Pinia są dobrymi narzędziami do zarządzania stanem, oficjalna dokumentacja Vue rekomenduje dziś przede wszystkim Pinię. Pinia wpisuje się w nowoczesne podejście Vue 3 i oferuje prostszy model pracy, który wymaga mniej kodu pomocniczego, a daje takie same lub lepsze efekty. Modułowe zarządzanie stanem z Pinią pomaga budować rozwiązania odporne na przyszłe zmiany w obsłudze stanu w aplikacjach Vue, dzięki czemu twoje projekty pozostają łatwe w utrzymaniu i skalowalne wraz z rozwojem.

Niezależnie od tego, czy wybierzesz Vuex ze względu na dojrzały ekosystem, czy Pinię za jej nowoczesną prostotę, stosowanie dobrych praktyk konfiguracji store’ów w Vue.js ma kluczowe znaczenie, jeśli projekt ma pozostać stabilny w miarę rozwoju. Jeśli zastosujesz wskazówki z tego poradnika, zbudujesz aplikacje, które łatwiej utrzymać, rozwijać i debugować.

Jeśli planujesz nową aplikację w Vue lub Nuxt albo porządkujesz zarządzanie stanem w już istniejącej, nasz zespół tworzący aplikacje w Vue.js pomoże ci zaprojektować architekturę store’ów, która będzie rozwijać się razem z twoim produktem.

Jeśli chcesz wejść w ten temat głębiej, zajrzyj do dodatkowych materiałów poniżej:

1. blog.logrocket.com: Zarządzanie złożonym stanem w Vue 3 z użyciem Pinia

2. tighten.com: Zarządzanie stanem w Vue 3: dlaczego warto wypróbować Pinię

3. digitalocean.com: Jak zarządzać stanem w aplikacji Vue.js za pomocą Vuex