Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Docs Roadmap #829

Open
6 of 20 tasks
posva opened this issue Nov 24, 2021 · 31 comments
Open
6 of 20 tasks

Docs Roadmap #829

posva opened this issue Nov 24, 2021 · 31 comments
Labels
📚 docs Related to documentation changes

Comments

@posva
Copy link
Member

posva commented Nov 24, 2021

These are the documentation sections I want to add or improve

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

@posva posva added the 📚 docs Related to documentation changes label Nov 24, 2021
@posva posva changed the title Docs Wishlist Docs Roadmap Dec 1, 2021
@jmroon
Copy link

jmroon commented Dec 12, 2021

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
Copy link
Contributor

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.

@posva posva mentioned this issue Dec 16, 2021
@jmroon
Copy link

jmroon commented Dec 20, 2021

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
Copy link
Contributor

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
Copy link

Jamiewarb commented Dec 24, 2021

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
Copy link
Member Author

posva commented Dec 24, 2021

@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 🙂

@aparajita
Copy link

aparajita commented Jan 21, 2022

@posva Documented how to split up a repo in a type-safe way here.

@tobiasdiez
Copy link

What I'm currently missing from the docs (also from the vuex ones) are some general guidelines and best practices to work with a store. Questions that would be nice to answer in this context:

  • For what kind of 'state' do you want to use a store over say component-wise reactive variables
  • How much logic do you put in the actions of the store vs in composables that use the store (e.g. should a login action only set isLoggedIn and currentUser or should it also call the API to fetch the new user config [which would be handled in a different store] and do some general logging for stats etc).

@pontakornth

This comment was marked as resolved.

@taist24

This comment was marked as resolved.

@posva

This comment was marked as resolved.

@J3m5
Copy link

J3m5 commented Apr 4, 2022

Could the addition and typing of getters with the plugin API be documented too? (#1196)

@bart-1990

This comment was marked as off-topic.

@posva

This comment was marked as off-topic.

@bart-1990

This comment was marked as off-topic.

@nazarepiedady

This comment was marked as resolved.

@posva

This comment was marked as resolved.

@nazarepiedady

This comment was marked as resolved.

@posva

This comment was marked as resolved.

@seahurt

This comment was marked as outdated.

@SchDen
Copy link

SchDen commented Oct 15, 2022

👍 I'm looking forward "native" way to split a store

@jamesli2021
Copy link

jamesli2021 commented Nov 2, 2022

The basic example should be rewritten in a clear structure that we can switch between Option and Composition API, overlap between option and composition is awful hard to read, confusing and overwhelm for new readers, my mind went blank despite an experienced programmer.

It feels like a tutorial written by someone's personal notebook?
https://pinia.vuejs.org/introduction.html#basic-example

I agree #1265 is worth it and should follow Vue way.

@nazarepiedady

This comment was marked as resolved.

@posva

This comment was marked as resolved.

@nazarepiedady

This comment was marked as off-topic.

@posva

This comment was marked as off-topic.

@emahuni
Copy link

emahuni commented Dec 13, 2022

I don't know if this has been considered, but it seems like Pinia can be used in a "namespace" way of handling stores that Vuex did. I really wanted to separate stores that are based off the same store file... eg:

// selection.store.js
export const useStore = ({ namespace }={}) => {
  const storeID = `selection${namespace ? `:${namespace}` : '' }`;

  const store = defineStore(storeID, {
    state: () => ({
        current:  undefined,
        previous: undefined,
        // ...
    }),

    getters: {
      // ....
    },

    actions: {
      // ....
    },
  })();

  return store;
};

Instead of writing 5 different stores that do the same thing using the same content I just do this:

import { useStore } from 'stores/selection.store.js';
// ... define and use each store wherever needed in a separate namespace
const selectOneStore = useStore({ namespace: 'one' }); // storeID => selection:one
const selectTwoStore = useStore({ namespace: 'two' }); // storeID => selection:two
const selectThreeStore = useStore({ namespace: 'three' }); // storeID => selection:three
const selectFourStore = useStore({ namespace: 'four' }); // storeID => selection:four
// ... do whatever with stores wherever each store is being used

// ... if the same is being used without any namespacing
const selectionStore = useStore(); // storeID => selection

... and now have stores selection:one, selection:two, selection:three, selection:four and selection that are independent from each other but use the same logic.

They can be used by different things that handle completely different use cases, but use the same logic. They also appear in dev tools as different stores. The best thing is there is nothing weird or hacky on Pinia, it's just how one defines the stores.

I wish this is documented somewhere so that users can use this method of defining stores and also help transition Vuex code.

@miecio1212

This comment was marked as resolved.

This comment was marked as resolved.

@miecio1212

This comment was marked as resolved.

@DamianGlowala
Copy link

DamianGlowala commented Feb 6, 2024

Could we add the docs for how to properly dispose a store, reset its state or do both (dispose and reset)?

I didn't know dispose doesn't reset the state, and, most of all, wasn't aware these two exist at all before looking into the GitHub issues.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
📚 docs Related to documentation changes
Projects
Status: 📋 Backlog
Development

No branches or pull requests