.github/workflows/test-multiple-versions.yml

@@ -33,8 +33,8 @@ jobs:
           - 18.0.0
           - 18.1.0
           - 18.2.0
-          - 18.3.0-canary-aef7ce554-20230503
-          - 0.0.0-experimental-aef7ce554-20230503
+          - 18.3.0-canary-53ac21937-20230703
+          - 0.0.0-experimental-53ac21937-20230703
         devtools-skip:
           - CI-MATRIX-NOSKIP
         include:

docs/guides/auto-generating-selectors.md

@@ -62,7 +62,7 @@ Now the selectors are auto generated and you can access them directly:
 const bears = useBearStore.use.bears()
 
 // get the action
-const increase = useBearStore.use.increment()
+const increment = useBearStore.use.increment()
 ```
 
 ## Live Demo

docs/guides/connect-to-state-with-url-hash.md

@@ -1,9 +1,9 @@
 ---
-title: Connect to state with URL hash
+title: Connect to state with URL
 nav: 12
 ---
 
-## State is connected with URL hash
+## Connect State with URL Hash
 
 If you want to connect state of a store to URL hash, you can create your own hash storage.
 
@@ -15,7 +15,7 @@ const hashStorage: StateStorage = {
   getItem: (key): string => {
     const searchParams = new URLSearchParams(location.hash.slice(1))
     const storedValue = searchParams.get(key) ?? ''
-    return storedValue
+    return JSON.parse(storedValue)
   },
   setItem: (key, newValue): void => {
     const searchParams = new URLSearchParams(location.hash.slice(1))
@@ -43,6 +43,101 @@ export const useBoundStore = create(
 )
 ```
 
-## CodeSandbox Demo
+### CodeSandbox Demo
 
-https://codesandbox.io/s/zustand-state-with-url-hash-demo-pn20n5?file=/src/store/index.ts
+https://codesandbox.io/s/zustand-state-with-url-hash-demo-f29b88?file=/src/store/index.ts
+
+## Persist and Connect State with URL Parameters (Example: URL Query Parameters)
+
+There are times when you want to conditionally connect the state to the URL.
+This example depicts usage of the URL query parameters
+while keeping it synced with another persistence implementation, like `localstorage`.
+
+If you want the URL params to always populate, the conditional check on `getUrlSearch()` can be removed.
+
+The implementation below will update the URL in place, without refresh, as the relevant states change.
+
+```ts
+import { create } from 'zustand'
+import { persist, StateStorage, createJSONStorage } from 'zustand/middleware'
+
+const getUrlSearch = () => {
+  return window.location.search.slice(1)
+}
+
+const persistentStorage: StateStorage = {
+  getItem: (key): string => {
+    // Check URL first
+    if (getUrlSearch()) {
+      const searchParams = new URLSearchParams(getUrlSearch())
+      const storedValue = searchParams.get(key)
+      return JSON.parse(storedValue)
+    } else {
+      // Otherwise, we should load from localstorage or alternative storage
+      return JSON.parse(localStorage.getItem(key))
+    }
+  },
+  setItem: (key, newValue): void => {
+    // Check if query params exist at all, can remove check if always want to set URL
+    if (getUrlSearch()) {
+      const searchParams = new URLSearchParams(getUrlSearch())
+      searchParams.set(key, JSON.stringify(newValue))
+      window.history.replaceState(null, null, `?${searchParams.toString()}`)
+    }
+
+    localStorage.setItem(key, JSON.stringify(newValue))
+  },
+  removeItem: (key): void => {
+    const searchParams = new URLSearchParams(getUrlSearch())
+    searchParams.delete(key)
+    window.location.search = searchParams.toString()
+  },
+}
+
+let localAndUrlStore = (set) => ({
+  typesOfFish: [],
+  addTypeOfFish: (fishType) =>
+    set((state) => ({ typesOfFish: [...state.typesOfFish, fishType] })),
+
+  numberOfBears: 0,
+  setNumberOfBears: (newNumber) =>
+    set((state) => ({ numberOfBears: newNumber })),
+})
+
+let storageOptions = {
+  name: 'fishAndBearsStore',
+  storage: persistentStorage,
+}
+
+const useLocalAndUrlStore = create(persist(localAndUrlStore, storageOptions))
+
+export default localAndUrlStore
+```
+
+When generating the URL from a component, you can call buildShareableUrl:
+
+```ts
+const buildURLSuffix = (params, version = 0) => {
+  const searchParams = new URLSearchParams()
+
+  const zustandStoreParams = {
+    state: {
+      typesOfFish: params.typesOfFish,
+      numberOfBears: params.numberOfBears,
+    },
+    version: version, // version is here because that is included with how Zustand sets the state
+  }
+
+  // The URL param key should match the name of the store, as specified as in storageOptions above
+  searchParams.set('fishAndBearsStore', JSON.stringify(zustandStoreParams))
+  return searchParams.toString()
+}
+
+export const buildShareableUrl = (params, version) => {
+  return `${window.location.origin}?${buildURLSuffix(params, version)}`
+}
+```
+
+The generated URL would look like (here without any encoding, for readability):
+
+`https://localhost/search?fishAndBearsStore={"state":{"typesOfFish":["tilapia","salmon"],"numberOfBears":15},"version":0}}`

docs/guides/flux-inspired-practice.md

@@ -3,27 +3,47 @@ title: Flux inspired practice
 nav: 5
 ---
 
-Although zustand is an unopinionated library, here are some patterns we recommend:
+Although Zustand is an unopinionated library, we do recommend a few patterns.
+These are inspired by practices originally found in [Flux](https://github.com/facebookarchive/flux),
+and more recently [Redux](https://redux.js.org/understanding/thinking-in-redux/three-principles),
+so if you are coming from another library, you should feel right at home.
 
-- Create a single store;
-- Always use `set` to define a store;
-- Define your dispatch functions at the root level of the store to update one or more store slices.
+However, Zustand does differ in some fundamental ways,
+so some terminology may not perfectly align to other libraries.
+
+## Recommended patterns
+
+### Single store
+
+Your applications global state should be located in a single Zustand store.
+
+If you have a large application, Zustand supports [splitting the store into slices](./slices-pattern).
+
+### Use `set` / `setState` to update the store
+
+Always use `set` (or `setState`) to perform updates to your store.
+`set` (and `setState`) ensures the described update is correctly merged and listeners are appropriately notified.
+
+### Colocate store actions
+
+In Zustand, state can be updated without the use of dispatched actions and reducers found in other Flux libraries.
+These store actions can be added directly to the store as shown below.
+
+Optionally, by using `setState` they can be [located external to the store](./practice-with-no-store-actions.md)
 
 ```js
 const useBoundStore = create((set) => ({
   storeSliceA: ...,
   storeSliceB: ...,
   storeSliceC: ...,
-  dispatchX: () => set(...),
-  dispatchY: () => set(...),
+  updateX: () => set(...),
+  updateY: () => set(...),
 }))
 ```
 
-See [Splitting the store into separate slices](./slices-pattern.md) for how to define a store with separate slices.
-
-## Flux like patterns / "dispatching" actions
+## Redux-like patterns
 
-If you can't live without redux-like reducers, you can define a `dispatch` function on the root level of the store like so:
+If you can't live without Redux-like reducers, you can define a `dispatch` function on the root level of the store:
 
 ```typescript
 const types = { increase: 'INCREASE', decrease: 'DECREASE' }

docs/guides/how-to-reset-state.md

@@ -47,7 +47,7 @@ const useSlice = create<State & Actions>()((set, get) => ({
 Resetting multiple stores at once
 
 ```ts
-import { create: _create, StateCreator } from 'zustand'
+import { create as _create, StateCreator } from 'zustand'
 
 const resetters: (() => void)[] = []