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). +::