Docs Roadmap

[posva]

These are the documentation sections I want to add or improve

• Migrate to Vue.js theme
  • Use a neutral font ([Docs]: Dank Mono is hard to read as someone visually and cognitively impaired #873)
  • Adapt instructions for Vue 2.7
• Cookbook
  • Testing
    • Initializing the store before
    • What is needed for Nuxt (maybe link to another page) (Nuxt 2 Jest context #910)
    • Document action usage within setup stores cannot be stubbed Given a TestingPinia instance of a store with a watch, the watch actions are not stubbed #2291
  • Advanced reactivity
    • Show how to use composables inside option and setup stores
  • Spltting the store into multiple files (How to split store in different files? And the limits of object type inference #802)
  • Allowing making a Store implement an interface (state, actions, or/and getters)
  • Advanced SSR
    • Hydrating differing state like useLocalStorage()
    • Differences between Setup and Option stores
    • Using stores before hydration Weird behavior with SSR #948
  • Handling Errors with API calls
  • CDN installation for Vue 2 and Vue 3 Using Pinia standalone (CDN or UNPKG) mode #1051
• State must be defined as a whole storeToRefs not working with optional parameters, when not explicitly set to undefined #1335
• Setup Stores (Setup store - A more comprehensive example #978)
  • Currently only Option stores are documented properly. It would be nice to have a switch somewhere or to mention them early on and link to a cookbook entry about advanced reactivity as these stores allow patterns that are impossible (or not intuitive) to achieve with the options API, like watching
• Being able to switch between syntaxes (option / setup store) (TBD if worth) make doc site toggle between options and composition api just like vue site #1265
• Reorganize the What is Pinia and Getting Started sections so the latter shows complete examples (Pinia's "Getting started" page lacks a basic example. #1195)
• Add note about patch modifying in place objects $patch function replace value in remote object #1921

If you have suggestions about common use cases that are not covered or improvement / refactoring for the existing docs, please share

How to contribute

If you want to contribute to the docs, make sure first there is no active Pull Request or an existing branch on this repository. Fork this repo, and create a Pull Request. You can mark it as WIP/Not ready for review if you need more time to work on it. This would avoid having two people working on the same thing.

If you are uncertain about anything you wrote, just leave a review on your own Pull Request so I can help.

Translations

If you want to contribute translations, only the Chinese and English versions are hosted within the repository. Other translations should be hosted elsewhere following the translation guidelines

[jmroon]

This is one thing I'd really appreciate clarified in the docs: mapStores.

I haven't had a chance to test it yet, but since the entire store is a computed property, I would assume that any modification of the store would result in re-rendering of all components subscribed to the store through mapStores. If this is the case, this is a pretty big caveat and should be documented clearly. I would suspect that due to the ease of using mapStores, a lot of users with big global stores might get into trouble.

[BenShelton]

I would assume that any modification of the store would result in re-rendering of all components subscribed to the store through mapStores

I don't think this is correct. If you had a "global" reactive object and imported it into multiple components, it would only trigger a render if part of that object is tracked and that specifically is changed. For example if in one component you access globalObj.prop1 within the template or in a computed etc. the render will only trigger if you changed the prop1 property on that object, whether it be within the component or elsewhere. That's the beauty of reactivity.

This concept is the same for stores, when created there's a global instance of them. Even if you imported the same store in every component (with mapStores or otherwise) it'll only trigger a change if a property has been tracked within that component, and that specific property changed. For example, you access myStore.prop2 within the template, it will only render again if prop2 is changed. If you don't access anything on the store, nothing is tracked, so any changes to the store won't cause a render.

I'm using the words track and trigger on purpose as that's in line with how the docs explain it, see https://v3.vuejs.org/guide/reactivity.html#how-rendering-reacts-to-changes & subsequent pages.

[jmroon]

I would assume that any modification of the store would result in re-rendering of all components subscribed to the store through mapStores

I don't think this is correct. If you had a "global" reactive object and imported it into multiple components, it would only trigger a render if part of that object is tracked and that specifically is changed. For example if in one component you access globalObj.prop1 within the template or in a computed etc. the render will only trigger if you changed the prop1 property on that object, whether it be within the component or elsewhere. That's the beauty of reactivity.

This concept is the same for stores, when created there's a global instance of them. Even if you imported the same store in every component (with mapStores or otherwise) it'll only trigger a change if a property has been tracked within that component, and that specific property changed. For example, you access myStore.prop2 within the template, it will only render again if prop2 is changed. If you don't access anything on the store, nothing is tracked, so any changes to the store won't cause a render.

I'm using the words track and trigger on purpose as that's in line with how the docs explain it, see https://v3.vuejs.org/guide/reactivity.html#how-rendering-reacts-to-changes & subsequent pages.

That's pretty amazing! Do you have any idea if this might hold true for Pinia in Vue 2 as well? After reading the docs it seems as though I might just need to be careful with property additions and array mutations. Arrays are a non issue, but I'm curious what'll happen if I set an optional prop after the fact.

I can certainly see myself using mapStores over the alternative, as it becomes more obvious when the code is accessing the store.

In any case, can't wait to move to a full Vue 3 + Pinia stack in the near future. Perfect reactivity and typescript support is going to be a major boon to development.

[BenShelton]

That's pretty amazing! Do you have any idea if this might hold true for Pinia in Vue 2 as well? After reading the docs it seems as though I might just need to be careful with property additions and array mutations. Arrays are a non issue, but I'm curious what'll happen if I set an optional prop after the fact.

Yep, same for Vue2 (with @vue/composition-api of course) there's some slight caveats as you mention but the general concept is the same. You can use set from composition-api to add additional properties in Vue2.

I can certainly see myself using mapStores over the alternative, as it becomes more obvious when the code is accessing the store.

I prefer it. It also helps with conversion to composition api because I tend to declare stores in setup like const userStore = useUserStore(). So if I move a method for example into the setup function I just remove the this. (so this.userStore.load() becomes userStore.load() for example) and it all works as before. Using the other map helpers needs a little more digging to find out where things came from originally.

In any case, can't wait to move to a full Vue 3 + Pinia stack in the near future. Perfect reactivity and typescript support is going to be a major boon to development.

Couldn't agree more.

[Jamiewarb]

I'm keen to write up some further documentation and cover some of these points. @posva Are there are works in progress for further documentation atm on any branches? And what's the best way to ask you a question if I run into something I'm unsure of while documenting?

-=-

And also to add a suggestion on something to document further:

When the store values differ on Server and Client, such as when using useStorage from Vueuse, the client store needs to be hydrated manually.

There's a section on that within the API reference part of the docs here: https://pinia.vuejs.org/api/interfaces/pinia.DefineStoreOptionsInPlugin.html#hydrate

However, I wanted to propose adding a small section on it under state within the Guide part of the docs.

I originally opened an issue for this, but see it may be better sat under this issue. I'm happy to open a PR to suggest potential documentation for that. Let me know what you think :)

[posva]

@Jamiewarb I added an item to the list and updated the issue about how to contribute. Let me know if it's missing anything!
I'm really keen on having cookbook entries contributed 🙂