From 7aa91ba894955c90093747d17504874e671899da Mon Sep 17 00:00:00 2001
From: Osama Abdallah Essa Haikal
 <72370395+OsamaHaikal@users.noreply.github.com>
Date: Sat, 7 Sep 2024 20:22:46 +0300
Subject: [PATCH] docs: add known limitations for app.config.ts (#28875)

---
 .../2.directory-structure/3.app-config.md     | 34 +++++++++++++++++++
 1 file changed, 34 insertions(+)

diff --git a/docs/2.guide/2.directory-structure/3.app-config.md b/docs/2.guide/2.directory-structure/3.app-config.md
index a027077a32..3e97d0e88b 100644
--- a/docs/2.guide/2.directory-structure/3.app-config.md
+++ b/docs/2.guide/2.directory-structure/3.app-config.md
@@ -121,3 +121,37 @@ export default defineAppConfig({
 ```
 
 ::
+
+## Known Limitations
+
+As of Nuxt v3.3, the `app.config.ts` file is shared with Nitro, which results in the following limitations:
+
+1. You cannot import Vue components directly in `app.config.ts`.
+2. Some auto-imports are not available in the Nitro context.
+
+These limitations occur because Nitro processes the app config without full Vue component support.
+
+While it's possible to use Vite plugins in the Nitro config as a workaround, this approach is not recommended:
+
+```ts [nuxt.config.ts]
+export default defineNuxtConfig({
+  nitro: {
+    vite: {
+      plugins: [vue()]
+    }
+  }
+})
+```
+
+::warning
+Using this workaround may lead to unexpected behavior and bugs. The Vue plugin is one of many that are not available in the Nitro context.
+::
+
+Related issues:
+- [Issue #19858](https://github.com/nuxt/nuxt/issues/19858)
+- [Issue #19854](https://github.com/nuxt/nuxt/issues/19854)
+
+::info
+Nitro v3 will resolve these limitations by removing support for the app config.
+You can track the progress in [this pull request](https://github.com/unjs/nitro/pull/2521).
+::