Pronounced like the fruit, in Spanish Piña
Piña is also an invalid package name... that's why it has to be pinia
🍍Automatically Typed, Modular and lightweight (but Experimental) Store for Vue based on the composition api with devtools support
Demo (TODO link)
What I want is to inspire others to think about ways to improve Vuex and come up with something that works very well with the composition api but that can also be used without it.
There are the core principles that I try to achieve with this experiment:
- Flat modular structure 🍍 No nesting, only stores, compose them as needed
- Light layer on top of Vue 💨 keep it under 1kg gzip
- Only
state
andgetters
👐patch
is the new mutation - Actions are just functions ⚗️ Group your business there
- Import what you need, let webpack code split 📦 No need for dynamically registered modules
- SSR support ⚙️
- DevTools support 💻 Which is crucial to make this enjoyable
A few notes about the project and possible questions:
Q: Does this replace Vuex, is it its successor?
A: No, or at least that's not the main intention
Q: What about dynamic modules?
A: Dynamic modules are not type safe, so instead we allow creating different stores that can be imported anywhere
- List Getters on DevTools
- Nuxt Module
- Automatic fresh store on Server Side?
- Flag to remove devtools support (for very light production apps)
- Allow grouping stores together into a similar structure and allow defining new getters
yarn add pinia
# or with npm
npm install pinia
You can create as many stores as you want, and they should each exist in isolated files:
import { createStore } from 'pinia'
export const useMainStore = createStore(
// name of the store
// it is used in devtools and allows restoring state
'main',
// a function that returns a fresh state
() => ({
counter: 0,
name: 'Eduardo',
}),
// optional getters
{
doubleCount: state => state.counter * 2,
}
)
createStore
returns a function that has to be called to get access to the store:
import { useMainStore } from '@/stores/main'
export default createComponent({
setup() {
const main = useMainStore()
return {
// gives access to the whole store
main,
// gives access to the state
state: main.state,
// gives access to specific getter,
}
},
})
There is one important rule for this to work: the useMainStore
(or any other useStore function) must be called inside of deferred functions. This is to allow the Vue Composition API plugin to be installed. Never, ever call useStore
like this:
import { useMainStore } from '@/stores/main'
// ❌ Depending on where you do this it will fail
// so just don't do it
const main = useMainStore()
export default createComponent({
setup() {
return {}
},
})
Once you have access to the store, you can access the state
through store.state
and any getter directly on the store
itself as a computed property (from @vue/composition-api
) (meaning you need to use .value
to read the actual value on the JavaScript but not in the template):
export default createComponent({
setup() {
const main = useMainStore()
const text = main.state.name
const doubleCount = main.doubleCount.value // notice the `.value` at the end
return {}
},
})
state
is the result of a ref
while every getter is the result of a computed
. Both from @vue/composition-api
.
To mutate the state you can either directly change something:
main.state.counter++
or call the method patch
that allows you apply multiple changes at the same time with a partial state
object:
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.
Simply set it to a new object;
main.state = { counter: 666, name: 'Paimon' }
The main part about SSR is not sharing state
between requests. So we can pass true
to useStore
once when getting a new request on the server. If we follow the SSR guide, our createApp
should look like this:
export function createApp() {
// Here there could also be a router
const store = useStore(true)
// we can change the state now!
store.state.counter++
// create the app instance
const app = new Vue({
render: h => h(App),
})
// expose the app and the store.
return { app, store }
}
Actions are simply function that contain business logic. As with components, they must call useStore
to retrieve the store:
export async function login(user, password) {
const store = useUserStore()
const userData = await apiLogin(user, password)
store.patch({
name: user,
...userData,
})
}
Composing stores may look hard at first glance but there is only one rule to follow really:
If multiple stores use each other or you need to use multiple stores at the same time, you must create a separate file where you import all of them.
If one store uses an other store, there is no need to create a new file, you can directly import it. Think of it as nesting.
If you need to compute a value based on the state
and/or getters
of multiple stores, you may be able to import all the stores but one into the remaining store, but depending on how your stores are used across your application, this would hurt your code splitting as you importing the store that imports all others stores, would result in one single big chunk with all of your stores.
To prevent this, we follow the rule above and we create a new file:
import { computed } from '@vue/composition-api'
import { useUserStore } from './user'
import { useCartStore } from './cart'
export const summary = computed(() => {
const user = useUserStore()
const cart = useCartStore()
return `Hi ${user.state.name}, you have ${cart.state.list.length} items in your cart. It costs ${cart.price}.`
})
When an actions needs to use multiple stores, we do the same, we create a new file:
import { useUserStore } from './user'
import { useCartStore, emptyCart } from './cart'
export async function orderCart() {
const user = useUserStore()
const cart = useCartStore()
try {
await apiOrderCart(user.state.token, cart.state.items)
emptyCart()
} catch (err) {
displayError(err)
}
}
Not implemented. Replaces the examles above about combining state and getters and about composing stores.
Combine multiple stores (gajos) into a new one:
import { pinia } from 'pinia'
import { useUserStore } from './user'
import { useCartStore, emptyCart } from './cart'
export const useCartUserStore = pinia(
{
user: useUserStore,
cart: useCartStore,
},
{
combinedGetter: state =>
`Hi ${user.state.name}, you have ${cart.state.list.length} items in your cart. It costs ${cart.price}.`,
}
)
export async function orderCart() {
const store = useCartUserStore()
try {
await apiOrderCart(store.state.user.token, store.state.cart.items)
emptyCart()
} catch (err) {
displayError(err)
}
}