From d61d239b4329f1ad054b275453fbc87ee572afcb Mon Sep 17 00:00:00 2001
From: derHodrig <53934248+derHodrig@users.noreply.github.com>
Date: Wed, 18 Dec 2024 10:37:34 +0100
Subject: [PATCH] docs: update auto-imports to advertise the scan feature
 (#30292)

---
 docs/2.guide/1.concepts/1.auto-imports.md | 22 ++++++++++++++++++++++
 packages/schema/src/config/adhoc.ts       |  5 +++++
 2 files changed, 27 insertions(+)

diff --git a/docs/2.guide/1.concepts/1.auto-imports.md b/docs/2.guide/1.concepts/1.auto-imports.md
index c650abc685..664c5de7d2 100644
--- a/docs/2.guide/1.concepts/1.auto-imports.md
+++ b/docs/2.guide/1.concepts/1.auto-imports.md
@@ -143,6 +143,28 @@ export default defineNuxtConfig({
 
 This will disable auto-imports completely but it's still possible to use [explicit imports](#explicit-imports) from `#imports`.
 
+### Partially Disabling Auto-imports
+
+If you want framework-specific functions like `ref` to remain auto-imported but wish to disable auto-imports for your own code (e.g., custom composables), you can set the `imports.scan` option to `false` in your `nuxt.config.ts` file:
+
+```ts
+export default defineNuxtConfig({
+  imports: {
+    scan: false
+  }
+})
+```
+
+With this configuration:
+- Framework functions like `ref`, `computed`, or `watch` will still work without needing manual imports.
+- Custom code, such as composables, will need to be manually imported in your files.
+
+::warning
+**Caution:** This setup has certain limitations:
+- If you structure your project with layers, you will need to explicitly import the composables from each layer, rather than relying on auto-imports.
+- This breaks the layer system’s override feature. If you use `imports.scan: false`, ensure you understand this side-effect and adjust your architecture accordingly.
+::
+
 ## Auto-imported Components
 
 Nuxt also automatically imports components from your `~/components` directory, although this is configured separately from auto-importing composables and utility functions.
diff --git a/packages/schema/src/config/adhoc.ts b/packages/schema/src/config/adhoc.ts
index 21660fa731..1d9f6a9d40 100644
--- a/packages/schema/src/config/adhoc.ts
+++ b/packages/schema/src/config/adhoc.ts
@@ -28,6 +28,11 @@ export default defineUntypedSchema({
    */
   imports: {
     global: false,
+    /**
+     * Whether to scan your `composables/` and `utils/` directories for composables to auto-import.
+     * Auto-imports registered by Nuxt or other modules, such as imports from `vue` or `nuxt`, will still be enabled.
+     */
+    scan: true,
 
     /**
      * An array of custom directories that will be auto-imported.