From a62f2ba3e3eea5c7f23083b38ee922c88efb4bc3 Mon Sep 17 00:00:00 2001
From: Michael Brevard <yonshi29@gmail.com>
Date: Fri, 5 Jan 2024 09:52:49 +0200
Subject: [PATCH] docs: warn about ref unwrapping when providing refs from
 plugin (#25054)

---
 docs/2.guide/2.directory-structure/1.plugins.md | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/docs/2.guide/2.directory-structure/1.plugins.md b/docs/2.guide/2.directory-structure/1.plugins.md
index 6851731978..ad17986912 100644
--- a/docs/2.guide/2.directory-structure/1.plugins.md
+++ b/docs/2.guide/2.directory-structure/1.plugins.md
@@ -200,6 +200,11 @@ const { $hello } = useNuxtApp()
 Note that we highly recommend using [`composables`](/docs/guide/directory-structure/composables) instead of providing helpers to avoid polluting the global namespace and keep your main bundle entry small.
 ::
 
+::callout{color="amber" icon="i-ph-warning-duotone"}
+**If your plugin provides a `ref` or `computed`, it will not be unwrapped in a component `<template>`.** :br
+This is due to how Vue works with refs that aren't top-level to the template. You can read more about it [in the Vue documentation](https://vuejs.org/guide/essentials/reactivity-fundamentals.html#caveat-when-unwrapping-in-templates).
+::
+
 ## Typing Plugins
 
 If you return your helpers from the plugin, they will be typed automatically; you'll find them typed for the return of `useNuxtApp()` and within your templates.