Vuex to Pinia. How to Migrate an Existing App

Hi there, are you ready to migrate your projects from UX to Pinia? Well, let's start together.

Hi, I'm Danny, I'm from Italy. I'm a full stack developer working with Python and JavaScript, and of course, Vue.js. And I work for Fingerprint as a front-end developer.

So, let's start with talking about Pinia. What is Pinia? Well, Pinia is the officially recognized state management library for Vue.js. Pinia started as an experiment to redesign what a store for Vue.js could look like with composition API. And of course, they tried to implement ideas and many things from core team discussion for VueX5. And then they saw that it was already there. So why applying again, the same changes to Vuex in order to create VueX5, when PNIA was already there. So let's give PNIA and make it the default recommendation now.

So before starting to migrate everything, let's check a quick comparison between VueX and PNIA. Of course, PNIA works with Vue.js 2 and 3 with the same version installed. So you don't need to install, for example, VueX 3 for Vue.js 2 and VueX 4 for Vue.js 3. You just need to install the latest PNIA available. And of course it works. And apart from these, it has a simpler API than VueX because mutations no longer exist. They were often perceived as extremely verbose. And again, with magic strings to inject and so on, they were a little bit difficult to use. So no need for mutations now, just actions, but we will see in a moment. And then you don't need to create custom complex wrappers to support TypeScript because, of course, it's, again, always implemented as a function or as an object. So it's perfect with auto-completion and so on. So no more magic strings to inject, import functions, import methods and properties, call them, and enjoy the completion. And you don't need to dynamically add stores because they are all dynamic by default. It's great. For the same reason, you don't need to nest modules and you don't need to create a nested structure for your store because they are kind of namespaced, you can say. And you can use a store inside another and it works. Just great.

So let's start by installing Pina. Pina can co-exist with Vuex, so you can install them together.

If you are using Vue.js 3 or 2.7, you can just install Pina. That's it, but if you are using Vue.js 2.6, you need to install also Vue composition API because Pina works with composition API. Then you can find a root store in a basic way. So just importing create Pina and using it in your application. Or if you're using Vue.js 2.x, you need to import also Pina Vue plugin and use the plugin before creating Pina. But if you want to create the root store in an advanced way, you need to create an index.js file in the stores directory, importing create Pina and creating the store. Kind of the same for Vue.js 2.x. And then in your main.js file, you can import your Pina from stores and use it in your application. So, everything Pina related will remain in the stores folder.

Then after defining the root store, let's call it the Pina instance, you need to define at least a store if you want to use a store. So, this is the syntax for Vue.js 3.x and 2.x as well. So, you need to define the store passing the name of the store as first parameter, and it needs to be unique between stores. And as second parameter, you need to pass the state, that is a function returning an object. And then getters and actions, of course no mutations, actions of course, no mutations, but actions changing the store state using just this. You can use a composition API syntax as well. It's kind of the same as the set up script, but the important thing to remember is that you need to return properties, getters, and actions at the bottom of the function, otherwise it won't work. But if you remember this, you can just define your reactive properties, computed and functions, and it works. It's really great.

Now in order to use the store in your components, you need to import store2refs. Store2refs if you want to use the syntax here, or just importing the store, your exported use store, then declaring the store. And from now on you can directly use the store, accessing state actions and getters from here. Or if you want to use reactive getters and properties in an easy way with variables, you can define them using a computed syntax like this or as I mentioned a couple seconds before, you can use store2refs in order to expand them in variables in a single line. No need for store2refs for actions because they are simple functions. So you can call them without the reactivity. For Vue.js 2, you need to import mapState and mapActions kind of similar to Vuex and of course, you store and then you can mapState and mapActions for wrapping state getters in mapState and actions, mapActions, of course. And you can use strings like we were doing in Vuex in Vuex or you can map them in this way.

So now it's time to migrate everything from Vuex to Binia. But before that, we need to prepare the migration in order to have everything sorted and everything ready to go. So let's take a look at the Vuex store structure. We have the store with index.js containing Vuex initialization, Imports modules, and the main store and other modules.

So keep in mind this structure for a moment. And for the store definition, I suggest you to slightly change your store definition to this. So extracting everything in a console. From default states to getters, mutations, actions, and modules. And then compose them in the store definition in order to migrate them one by one without problems or mix up of logic. Same for module, so you can export default state, getters, mutations, and actions and compose them in the module definition.

So, in order to migrate them, you just need to change from create store to define store and define the name of the store and use a function for the default state. And everything else is kind of the same. You just need to remove mutations and modules because there are no more modules for pinyin. And then you can change your state. Well, not really because the state is just an object so you can leave it like it was and it works. You just need to change getters because, well, if you were using getters like this, there's a need to change. The syntax is the same. But if you were using functions, well, these functions doesn't need to receive parameters because they can access this context, accessing other getters or the store state. So it works with this, not with state or getters. Same for mutations and actions.

So, well, mutations become actions. And then if they were using a state for accessing the store or getters or other mutations, you just need to use this and it works. So same for action, no need to pass the context as the first parameter, you just need to use this. And again it's great thing. Now, what about tests? Well, if you don't find test, of course, test won't fail, but if you are writing tests, you need to migrate them too. So, well, if you extracted the logic, like I mentioned before, test about the state doesn't change because they test just an object and they expect that it's like you are expecting. But if you are testing getters or mutations or actions, now you need to use .call in order to call getters or actions, and pass as first parameter of the call method, your current state, in order to test it and act on it. So same for mutations and actions, just pass the state in the call, mocking maybe functions or the store state, and you can use it like your store context. So let's look at a couple of examples here. This is the state test migration. So you just need to expect that the default state equals to what you need. For getters, this doesn't change because, well, we were using it in the old way. So passing state as first parameter. But in this case, we are passing the code with the context.

Same for mutations. So defining the state and passing it to the function. And of course, same for actions. So listen to the call to another action, and calling it, and expecting that it has been called. And well, in the end, if you want to test a real store for real behavior, you can, in this way. You need to create binya, and set the active binya in your test file, in the before-each test case. And in the test case, you can define the store, and use it like you are using it in the components or in your application, and it works. I'm not suggesting you this, because you are creating an entire binya instance before each test case, so it's kind of memory consuming. But if you want to test the real store, you can in this way.

Last but not least, we want to migrate our components. So like I mentioned, we need to import useStore from the correct store, and use it in this way. So with computed properties, or with store2Fs in a single line. And just import function like this from the store and use them.

For Vue.js too, we need to remove mapState, mapGetters, mapMutation, and so on from Vuex and use mapState and mapAction from vigname. We need to import the useStore and use mapState passing as first argument the useStore we need. And the second argument, a list of strings for properties and getters in mapState and functions in mapActions. Same for namespace modules. So we don't need create namespace diapers anymore. We just need to import the current state and use it in the same way.

Now it's time to test our components using Pina. So if you want to do a proper component testing for components using Pina, you need to install Pina testing. This is a great dependencies exposing this createTestingPina function that you need to call. If using vtest, you need to pass createSpy as argument defining what createPina needs to use for mocking your actions, for example. We'll see in a moment. And you can also pass the initial state. This is the name of the store you want to mock or define. And this is its values. So let's inspect createTestingPina. createTestingPina automatically mocks all actions. So you can unit test store and components separately in order to check for what components behavior and store behavior, but in a separate way. And of course, allows you to override getters value in tests. Keep in mind that this is not working with Vue.js 2 and Jet because you cannot override getters in Vue.js 2, but in Vue.js 3 is great. So you don't have to work around setting the fact predefined store state in order to make the getter in the value you need, you just need to mock the getter and overwrite its values. It's awesome. So let's see a couple of examples in component testing. An example with Vue 3 and VTest is like this. So before each test case, we need to create our testing Pina passing the mock function for the create spy. And of course, if you want initial state, and then you can find your store like this, then you can shallow mount your component passing Pina as global plugins. Same for Vue.js 2 and Jest.

So just need to create a local view, use your Pina vplugin and before each test case, create the testing Pina, passing the initial state and find the store. And then when mounting the component, you need to pass local view and Pina too. So, quick recap getters in Vue.js 2 and Jest are not writable. So you need to set the correct state in order to make them work as expected. So like this, if you want to set store count, you can write it or just patch the store if you need to update more properties at once. You can migrate your tests like this.

So moving create store and importing create testing Pina and new store. Removing the create store from Vuex and using create testing Pina. And again, importing the longer plugin Pina in the shallow mount and test everything like this. Same for VJSU, just import what you need, define your store instead of the Vuex store and pass it to the shallow function or mount function and everything should work. Well, yes, not exactly. So there are a couple migration problems. Let's call them migration knots.

So if you were using the store with a direct approach like this, now you need to import your store and access properties and getters using the store and no more store magic usage. Same for commit and dispatch. If you were using commit and dispatch from everywhere in your application, now you need to import store and call the current function, action function. Then another thing you need to remember is that if you are using store in this way outside of scripts tab, well, please remember not to write this in the root of your module, otherwise you can get this error because you don't have ActivePynea defined. So remember to prep it in a function and use it like that or use it in the scripts tab.

You may ask if Vuex and Pynea can coexist. Well, yes, of course, but when migrating, please remember to migrate entire modules and not entire components. So you need to make sure that a single module has been migrated before moving to another module just for order and simplicity of migration. So they can coexist, but you have just a single module from Vuex and that module can be migrated to Pynea, but other modules can be on Vuex while migrating. If you need store persistence, you can use it in this way in two ways, really, because you can subscribe to your store changes and set your, for example, local storage in your preferred way, and you can restore it when the application has been refreshed using mystore.state and settings.state, or you can watch. You can use a watcher in your application and watch for Pinion state changes and store them in a local storage variable, for example. And if you need to restore it, you can use pinion.state.value and set its value.

Now we reached the end of our migration. As final tasks, we need to remove Vuex from main.js. So just remove your import and your store usage. And then we can delete Vuex store and tests. And last but not least, we need to uninstall Vuex dependencies. So Vuex and for example, Vue CLI plugin Vuex. And that's it, we immigrated from Vuex to Pinia. Now I leave you a couple of links to of course the official documentation for Pinia and two repositories with moving to Pinia branch, so you can check and see what you need or you may want change for migrating from Vuex to Pinia.