From fc73a3a7edd1f8be55c3990d81edac5821f7ebc7 Mon Sep 17 00:00:00 2001
From: yf-yang <36890796+yf-yang@users.noreply.github.com>
Date: Tue, 30 Apr 2024 13:53:56 +0800
Subject: [PATCH] docs(scope): Add tips gathered from common issues (#29)

---
 README.md | 25 +++++++++++++++++++++++++
 1 file changed, 25 insertions(+)

diff --git a/README.md b/README.md
index 0f5a05c..58f501c 100644
--- a/README.md
+++ b/README.md
@@ -3,3 +3,28 @@
 👻🔭
 
 https://jotai.org/docs/integrations/scope
+
+## Pro Tips
+
+1. Within a `ScopeProvider`, although an atom may not be scoped, its `atom.read` function could be called multiple times. **Therefore, do not use `atom.read` to perform side effects.**
+
+    NOTE: Async atoms always have side effects. To handle it, add additional code to prevent extra side effects. You can check this [issue](https://github.com/jotaijs/jotai-scope/issues/25#issuecomment-2014498893) as an example.
+
+2. Scoping a derived atom has no behavioral effect. Avoid it.
+
+    Derived atoms are merely proxies of primitive atoms. When scoping a derived atom, although the atom itself is copied, all of those copies still reference the same primitive atom, so their values are still shared.
+
+    It is a common pattern in Jotai to wrap the primitive atom within a utility function. To scope it properly, you should expose the primitive atom and then apply the scoping to it.
+
+    ``` javascript
+    function someAtomUtility(initialValue) {
+      // This is the primitive atom. Return it and then scope it.
+      const anAtom = atom(initialValue)
+
+      // Be careful, this is a derived atom! Scoping it has no effect.
+      return atom(
+        (get) => get(anAtom),
+        (get, set, update) => set(anAtom, update)
+      ),
+    }
+    ```
\ No newline at end of file