From eacdfaa20de701cf8e27f4b4492d30b1c2c72011 Mon Sep 17 00:00:00 2001 From: Alex Liu Date: Sat, 8 Feb 2025 05:46:40 +0800 Subject: [PATCH] docs: add nuxt lifecycle (#30726) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Sébastien Chopin --- docs/2.guide/1.concepts/10.nuxt-lifecycle.md | 141 +++++++++++++++++++ 1 file changed, 141 insertions(+) create mode 100644 docs/2.guide/1.concepts/10.nuxt-lifecycle.md diff --git a/docs/2.guide/1.concepts/10.nuxt-lifecycle.md b/docs/2.guide/1.concepts/10.nuxt-lifecycle.md new file mode 100644 index 0000000000..743a9d9970 --- /dev/null +++ b/docs/2.guide/1.concepts/10.nuxt-lifecycle.md @@ -0,0 +1,141 @@ +--- +title: 'Nuxt Lifecycle' +description: "Understanding the lifecycle of Nuxt applications can help you gain deeper insights into how the framework operates, especially for both server-side and client-side rendering." +--- + +The goal of this chapter is to provide a high-level overview of the different parts of the framework, their execution order, and how they work together. + +## Server + +On the server, the following steps are executed for every initial request to your application: + +### Step 1: Setup Nitro Server and Nitro Plugins (Once) + +Nuxt is powered by [Nitro](https://nitro.build/), a modern server engine. + +When Nitro starts, it initializes and executes the plugins under the `/server/plugins` directory. These plugins can: +- Capture and handle application-wide errors. +- Register hooks that execute when Nitro shuts down. +- Register hooks for request lifecycle events, such as modifying responses. + +::callout{icon="i-ph-lightbulb"} +Nitro plugins are executed only once when the server starts. In a serverless environment, the server boots on each incoming request, and so do the Nitro plugins. However, they are not awaited. +:: + +:read-more{to="/docs/guide/directory-structure/server#server-plugins"} + +### Step 2: Nitro Server Middleware + +After initializing the Nitro server, middleware under `server/middleware/` is executed for every request. Middleware can be used for tasks such as authentication, logging, or request transformation. + +::warning +Returning a value from middleware will terminate the request and send the returned value as the response. This behavior should generally be avoided to ensure proper request handling! +:: + +:read-more{to="/docs/guide/directory-structure/server#server-middleware"} + +### Step 3: Initialize Nuxt and Execute Nuxt App Plugins + +The Vue and Nuxt instances are created first. Afterward, Nuxt executes its server plugins. This includes: +- Built-in plugins, such as Vue Router and `unhead`. +- Custom plugins located in the `plugins/` directory, including those without a suffix (e.g., `myPlugin.ts`) and those with the `.server` suffix (e.g., `myServerPlugin.server.ts`). + +Plugins execute in a specific order and may have dependencies on one another. For more details, including execution order and parallelism, refer to the [Plugins documentation](/docs/guide/directory-structure/plugins). + +::callout{icon="i-ph-lightbulb"} +After this step, Nuxt calls the [`app:created`](/docs/api/advanced/hooks#app-hooks-runtime) hook, which can be used to execute additional logic. +:: + +:read-more{to="/docs/guide/directory-structure/plugins"} + +### Step 4: Route Validation + +After initializing plugins and before executing middleware, Nuxt calls the `validate` method if it is defined in the `definePageMeta` function. The `validate` method, which can be synchronous or asynchronous, is often used to validate dynamic route parameters. + +- The `validate` function should return `true` if the parameters are valid. +- If validation fails, it should return `false` or an object containing a `statusCode` and/or `statusMessage` to terminate the request. + +For more information, see the [Route Validation documentation](/docs/getting-started/routing#route-validation). + +:read-more{to="/docs/getting-started/routing#route-validation"} + +### Step 5: Execute Nuxt App Middleware + +Middleware allows you to run code before navigating to a particular route. It is often used for tasks such as authentication, redirection, or logging. + +In Nuxt, there are three types of middleware: +- **Global route middleware** +- **Named route middleware** +- **Anonymous (or inline) route middleware** + +Nuxt automatically executes global middleware for first time enter to the application and every time before route navigation. Named and anonymous middleware are executed only on the routes specified in the middleware property of the page(route) meta defined in the corresponding page components. + +For details about each type and examples, see the [Middleware documentation](/docs/guide/directory-structure/middleware). + +Any redirection on the server will result in a `Location:` header being sent to the browser; the browser then makes a fresh request to this new location. All application state will be reset when this happens, unless persisted in a cookie. + +:read-more{to="/docs/guide/directory-structure/middleware"} + +### Step 6: Setup Page and Components + +Nuxt initializes the page and its components during this step and fetches any required data with `useFetch` and `useAsyncData`. Since there are no dynamic updates and no DOM operations occur on the server, Vue lifecycle hooks such as `onBeforeMount`, `onMounted`, and subsequent hooks are **NOT** executed during SSR. + +::important +You should avoid code that produces side effects that need cleanup in root scope of `