From: Eduardo San Martin Morote Date: Tue, 23 Mar 2021 09:27:04 +0000 (+0100) Subject: docs: cleanup readme [skip ci] X-Git-Tag: v2.0.0-alpha.8~18 X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=28ba2de807a394bd46090e6bacf1ac3fc0af49d3;p=thirdparty%2Fvuejs%2Fpinia.git docs: cleanup readme [skip ci] --- diff --git a/README.md b/README.md index 24ab3cda..07e3def0 100644 --- a/README.md +++ b/README.md @@ -172,279 +172,9 @@ export default defineComponent({ }) ``` -Note: the SSR implementation on Pinia might change, but if you intend having SSR on your application, you should avoid using `useStore` functions at the root level of a file to make sure the correct store is retrieved for your currently running application instance. Here is an example: +## Documentation -**Avoid doing this**: - -```ts -import { createRouter } from 'vue-router' -const router = createRouter({ - // ... -}) - -// ❌ Depending on where you do this it will fail -const main = useMainStore() - -router.beforeEach((to, from, next) => { - if (main.isLoggedIn) next() - else next('/login') -}) -``` - -Instead, call `useMainStore()` at the top of `setup`, like `inject` and `provide` in Vue: - -```ts -export default defineComponent({ - setup() { - // ✅ This will work - const main = useMainStore() - - return {} - }, -}) - -// In a different file... -const pinia = createPinia() -app.use(pinia) - -router.beforeEach((to) => { - // ✅ This will work (requires pinia param when outside of setup on both - // Client and Server. See the SSR section below for more information) - const main = useMainStore(pinia) - - if (to.meta.requiresAuth && !main.isLoggedIn) return '/login' -}) -``` - -⚠️: Note that if you are developing an SSR application, [you will need to do a bit more](#ssr). - -You can access any property defined in `state` and `getters` directly on the store, similar to `data` and `computed` properties in a Vue component. - -```ts -export default defineComponent({ - setup() { - const main = useMainStore() - const text = main.name // "eduardo" - const doubleCount = main.doubleCount // 2 - - return { - text, // will always be "eduardo" - textDynamic: computed(() => main.name), // reactive value - } - }, -}) -``` - -The `main` store in an object wrapped with `reactive`, meaning there is no need to write `.value` after getters but, like `props` in `setup`, we cannot destructure it: - -```ts -export default defineComponent({ - setup() { - // ❌ This won't work because it breaks reactivity - // it's the same as destructuring from `props` - const { name, doubleCount } = useMainStore() - return { name, doubleCount } - }, -}) -``` - -Actions are invoked like methods: - -```ts -export default defineComponent({ - setup() { - const main = useMainStore() - // call the action as a method of the store - main.reset() - - return {} - }, -}) -``` - -### Mutating the `state` - -To mutate the state you can either directly change something: - -```ts -main.counter++ -``` - -or call the method `$patch` that allows you apply multiple changes at the same time with a partial `state` object: - -```ts -main.$patch({ - counter: -1, - name: 'Abalam', -}) -``` - -The main difference here is that `$patch` allows you to group multiple changes into one single entry in the devtools. - -### Replacing the `state` - -Simply set your store `$stet` property to a new object: - -```ts -main.$state = { counter: 666, name: 'Paimon' } -``` - -### SSR - -Creating stores with Pinia should work out of the box for SSR as long as you call your `useStore()` functions at the top of `setup` functions, `getters` and `actions`: - -```ts -export default defineComponent({ - setup() { - // this works because pinia knows what application is running - const main = useMainStore() - return { main } - }, -}) -``` - -If you need to use the store somewhere else, you need to pass the `pinia` instance [that was passed to the app](#install-the-plugin) to the `useStore()` function call: - -```ts -const pinia = createPinia() -const app = createApp(App) - -app.use(router) -app.use(pinia) - -router.beforeEach((to) => { - // ✅ This will work make sure the correct store is used for the current running app - const main = useMainStore(pinia) - - if (to.meta.requiresAuth && !main.isLoggedIn) return '/login' -}) -``` - -To hydrate the initial state, you need to make sure the rootState is included somewhere in the HTML for Pinia to pick it up later on: - -```js -import { createPinia } from 'pinia' -// retrieve the rootState server side -const pinia = createPinia() -const app = createApp(App) -app.use(router) -app.use(pinia) - -// after rendering the page, the root state is build and can be read -// serialize, escape (VERY important if the content of the state can be changed -// by the user, which is almost always the case), and place it somewhere on -// the page, for example, as a global variable. Note you need to use your own -// `escapeHTML()` function or use an existing package -escapeHTML(JSON.stringify(pinia.state.value)) -``` - -On client side, you must hydrate pinia's state before calling any `useStore()` function. For example, if we serialize the state into a `