Vuex to Pinia. How to Migrate an Existing App

Hi there! Are you ready to migrate your projects from UX to PNIA? Well, let's start together! I am 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 frontend developer. So let's start with talking about PNIA. What is PNIA? Well, PNIA is the officially recognized state management library for vue.js. PNIA started as an experiment to redesign what a store for vue.js could look like with composition api. Of course they tried to implement ideas and many things from core team discussion for vue.x5 and then they saw that it was already there. So why apply again the same changes to vue.x in order to create vue.x5 when PNIA was already there? So let's skip PNIA and make it the default recommendation now. So before starting to migrate everything, let's check a quick comparison between vue.x 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, vue.x3 for vue.js 2 and vue.x4 for vue.js 3. You just need to install the latest PNIA available and of course it works. Apart from this, it has a simpler api than vue.x 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. 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, imports functions, imports methods and properties, call them and enjoy the completion. 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 Pinyin. Pinyin can coexist with vuex so you can install them together. If you are using vue.js 3 or 2.7, you can just install Pinyin and that's it. But if you are using vue.js 2.6, you need to install also vue.js Composition api because Pinyin works with Composition api. Then you can define a root store in a basic way. So just importing createPinyin and using it in your application. Or if you are using vue 2.x, you need to import also PinyinVuePlugin and use the plugin before creating Pinyin. 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 createPinyin and creating the store, kind of the same for vue.js 2.x. And then in your main.js file, you can import your Pinyin from stores and use it in your application. So everything Pinyin related will remain in the stores folder. Then after defining the root store, let's call it the Pinyin 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 and 2 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, 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 setup 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 if you want to use the syntax here, or just importing the store, your exported useStore, 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 time. No need for store2refs for actions because they are simple functions, so you can call them without the reactivity. From useJS2, you need to import mapState and mapActions, kind of similar to vuex, and of course, the useStore, and then you can mapState and mapActions for mapping state getters in mapState, and actions, mapActions, of course. You can use strings like we were doing in vuex, or you can map them this way. So now it's time to migrate everything from vuex to Pina, 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 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 createStore in vuex to defineStore 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 no need to change, the syntax is the same, but if you were using functions, well, these functions don't need to receive parameters because they can access this context, accessing other getters, or the store state, so it works with this, no, 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 Pinyin. Now, what about tests? Well, if you don't write tests, of course tests 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 the old way. So passing the state as first parameter, but in this case, we are passing the call with the context. Same for mutations. So defining the state and passing it to the function. And of course, same for actions. So listening to the call to another action and calling it and expecting that has been called. And, well, in the end, if you want to test a real store for real behavior, you can in this way. So you need to create Pinya and set the active Pinya in your test file, in the beforeEach 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 Pinya instance beforeEach 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 the useStore from the correct store and use it in this way. So with computed properties or with storeToRefs 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, mapUtation, and so on from vuex and use mapState and mapAction from Pinya. 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 createNamespaceDeadPars 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 Pinya. So if you want to do a proper component testing for components using Pinya, you need to install Pinya testing. This is great dependencies exposing this createTestingPinya function that you need to call if using vTest you need to pass createSpy as argument defining what createPinya needs to use for mocking your actions, for example, we will 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 createTestingPinya. createTestingPinya automatically mocks all actions. So you can unit test store and components separately in order to check for components behavior and store behavior, but in a separate way. And of course, allows you to overwrite getters value in tests. Keep in mind that this is not working with vue.js 2 and Jest because you cannot overwrite getters in vue.js 2, but in vue.js 3 it's great. So you don't have to work around setting up the predefined store state in order to make 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 testingPinya passing the mock function for the createSpy and of course, if you want initial state, and then you can define your store like this. Then you can shallow mount your component passingPinya as global plugins. Same for vue.js 2 and Jest. So just need to create local vue, use your PinyaVue plugin and before each test case, create the testingPinya passing the initial state and define the store. And then when mounting the component, you need to pass localVue and Pinya2. So quick recap, getters in vue.js 2 and Jest are not writeable, 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 createStore and importing createTestingPinya and newStore. Removing the createStore from vuex and using createTestingPinya. And again, importing the global plugin Pinya in the shallow mount and test everything like this. Same for vue.js 2, just import what you need, define your store instead of the vuex store and pass it to the shallow mount function and everything should work. Well, yes, not exactly. So there are a couple of 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 active Pinya defined. So remember to prop it in a function and use it like that or use it in the scripts tab. You may ask if vuex and Pinya 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 Pinya, 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 setting state. Or you can watch, you can use a watcher in your application and watch for Pinya.state changes and store them in a local storage variable, for example. And if you need to restore it, you can use Pinya.state.value and set this 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 migrated from vuex to Pinya. Now I leave you a couple of links to, of course, the official documentation for Pinya and two repositories with moving to Pinya branch so you can check and see what you need or you may want to change for migrating from vuex to Pinya. And that's it. Bye everyone. I'm John Furrier.