From 341fbe60f90a6079a391d573569ac9f32552051c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jakub=20Bedn=C3=A1r?=
 <33372892+jakubednar@users.noreply.github.com>
Date: Mon, 13 May 2024 22:59:33 +0200
Subject: [PATCH] docs: add module execution order (#27178)

---
 docs/2.guide/2.directory-structure/1.modules.md | 6 +++++-
 packages/schema/src/config/common.ts            | 3 ++-
 2 files changed, 7 insertions(+), 2 deletions(-)

diff --git a/docs/2.guide/2.directory-structure/1.modules.md b/docs/2.guide/2.directory-structure/1.modules.md
index 2664e5601e..ce9de8f9f2 100644
--- a/docs/2.guide/2.directory-structure/1.modules.md
+++ b/docs/2.guide/2.directory-structure/1.modules.md
@@ -46,7 +46,11 @@ export default defineEventHandler(() => {
 
 When starting Nuxt, the `hello` module will be registered and the `/api/hello` route will be available.
 
-Local modules are registered in alphabetical order. You can change the order by adding a number to the front of each directory name:
+Modules are executed in the following sequence:
+- First, the modules defined in [`nuxt.config.ts`](/docs/api/nuxt-config#modules-1) are loaded.
+- Then, modules found in the `modules/` directory are executed, and they load in alphabetical order.
+
+You can change the order of local module by adding a number to the front of each directory name:
 
 ```bash [Directory structure]
 modules/
diff --git a/packages/schema/src/config/common.ts b/packages/schema/src/config/common.ts
index 42191feace..b42b9a5e59 100644
--- a/packages/schema/src/config/common.ts
+++ b/packages/schema/src/config/common.ts
@@ -236,7 +236,8 @@ export default defineUntypedSchema({
    *
    * Nuxt tries to resolve each item in the modules array using node require path
    * (in `node_modules`) and then will be resolved from project `srcDir` if `~` alias is used.
-   * @note Modules are executed sequentially so the order is important.
+   * @note Modules are executed sequentially so the order is important. First, the modules defined in `nuxt.config.ts` are loaded. Then, modules found in the `modules/`
+   * directory are executed, and they load in alphabetical order.
    * @example
    * ```js
    * modules: [