docs: added caveats docs

docs/.vitepress/config.ts

@@ -41,10 +41,6 @@ export default defineConfig({
 
         items: [
           { text: 'Extending', link: '/advanced/extending' },
-          {
-            text: 'Performance',
-            link: '/advanced/performance',
-          },
           {
             text: 'Caveats',
             link: '/advanced/caveats',

docs/.vitepress/theme/config.css

@@ -39,6 +39,7 @@
   --vp-button-sponsor-active-bg: transparent;
 }
 
-a {
+.vp-doc a {
   text-decoration: dashed;
+  font-weight: bold;
 }

docs/advanced/caveats.md

@@ -57,7 +57,11 @@ Here is a benchmark of the difference between using a Proxy object and a plain o
 
 Source: [Proxy vs Plain Object](https://www.measurethat.net/Benchmarks/Show/12503/0/object-vs-proxy-vs-proxy-setter)
 
-### Example
+If you are forced to use reactivity, use [shallowRef](https://vuejs.org/api/reactivity-advanced.html#shallowref)
+
+Unlike `ref()`, the inner value of a shallow ref is stored and exposed as-is, and will not be made deeply reactive. Only the .value access is reactive. Source [VueJS Docs](https://vuejs.org/api/reactivity-advanced.html#shallowref)
+
+### Example
 
 ❌ Incorrect
 
@@ -82,7 +86,7 @@ onLoop(({ _delta, elapsed }) => {
 ```vue
 <script setup lang="ts">
 const position = { x: 0, y: 0, z: 0 }
-const boxRef: Ref<TresInstance | null> = ref(null)
+const boxRef: ShallowRef<TresInstance | null> = shallowRef(null)
 
 onLoop(({ _delta, elapsed }) => {
   boxRef.value.position.x = Math.sin(elapsed * 0.1) * 3

docs/examples/basic-animations.md

@@ -25,9 +25,11 @@ onLoop(({ _delta, elapsed }) => {
 
 To animate the cube, we need to get a reference to it. We can do it by passing a [Template Ref](https://vuejs.org/guide/essentials/template-refs.html) using `ref` prop to the `TresMesh` component. This will return the THREE instance.
 
+To improve the performance, we will use a [Shallow Ref](https://v3.vuejs.org/guide/reactivity-fundamentals.html#shallow-reactivity) to store the reference instead of a regular Ref. See why [here](../advanced/caveats.md#reactivity)
+
 ```vue
 <script setup lang="ts">
-const boxRef: Ref<TresInstance | null> = ref(null)
+const boxRef: ShallowRef<TresInstance | null> = shallowRef(null)
 </script>
 
 <template>