docs: add pre-rendering page

Author: atinux

docs/content/docs/4.recipes/3.pre-rendering.md

@@ -0,0 +1,118 @@
+---
+title: Pre-rendering
+description: Pre-render pages at build time for maximum performance and avoid CPU usage on the server.
+---
+
+When using NuxtHub, you need to build your application with the [`nuxt build`](https://nuxt.com/docs/api/commands/build) in order to keep your server when deploying your application.
+
+However, you can also pre-render your pages at build time to improve performance and avoid CPU usage on the server.
+
+::tip{to="https://nuxt.com/docs/guide/concepts/rendering#hybrid-rendering"}
+This is possible thanks to **Nuxt's Hybrid Rendering** to allow different caching rules per route.
+::
+
+## Route Rules
+
+### Globally
+
+You can define route rules in your `nuxt.config.ts` to specify how each route should be rendered:
+
+```ts [nuxt.config.ts]
+export default defineNuxtConfig({
+  routeRules: {
+    '/': { prerender: true }
+  }
+})
+```
+
+When running `nuxt build`, Nuxt will pre-render the `/` route and save the `index.html` file in the output directory. 
+
+::callout{icon="i-ph-rocket-launch-duotone"}
+When deploying with NuxtHub on Cloudflare Pages, it will serve the pre-rendered HTML file directly from the edge for maximum performance and avoid CPU usage on the server.
+::
+
+### Page Level
+
+It is also possible to define route rules at the page level using the [`defineRouteRules`](https://nuxt.com/docs/api/utils/define-route-rules) util in the page component:
+
+```vue [pages/index.vue]
+<script setup lang="ts">
+defineRouteRules({
+  prerender: true
+})
+</script>
+
+<template>
+  <h1>Hello world!</h1>
+</template>
+```
+
+This is equivalent of our example above in the `nuxt.config.ts` file.
+
+**Notes:**
+- A rule defined in `~/pages/foo/bar.vue` will be applied to `/foo/bar` requests.
+- A rule in `~/pages/foo/[id].vue` will be applied to `/foo/**` requests.
+
+::important{to="https://nuxt.com/docs/guide/going-further/experimental-features#inlinerouterules"}
+As this is an experimental feature, you need to enable it in your `nuxt.config.ts` files with `experimental: { inlineRouteRules: true }`.
+::
+
+## Dynamic Pre-rendering
+
+In some cases, you may want to Nuxt to pre-render other pages when pre-rendering a specific page.
+
+This is useful when pre-rendering all the blog posts when pre-rendering the blog index page. To achieve this, we can use the [`prerenderRoutes`](https://nuxt.com/docs/api/utils/prerender-routes) util in the page component:
+
+```vue [pages/blog/index.vue]
+<script setup lang="ts">
+// Pre-render the /blog page
+defineRouteRules({ prerender: true })
+
+const { data: posts } = await useFetch('/api/posts')
+
+// Tell Nuxt to pre-render all blog posts
+prerenderRoutes(posts.value.map(post => `/blog/${post.slug}`))
+</script>
+```
+
+It is important to tell Nuxt to pre-render the `/blog` using the `defineRouteRules`, we can also do it globally in the `nuxt.config.ts` file.
+
+```ts [nuxt.config.ts]
+export default defineNuxtConfig({
+  routeRules: {
+    // If not using `defineRouteRules` in the page component
+    '/blog': { prerender: true }
+  }
+})
+```
+
+## Caveats
+
+If you are using authentication in your application such as [`nuxt-auth-utils`](https://github.com/Atinux/nuxt-auth-utils), you need to remember that the authentication state will not be available during the pre-rendering process.
+
+For example, if you have a header component that either display the logged in user or a login button, you need to wrap the logic inside [`<ClientOnly>`](https://nuxt.com/docs/api/components/client-only) component to avoid displaying the login button when the user is already logged in.
+
+```vue [components/AppHeader.vue]
+<script setup lang="ts">
+const { loggedIn, user } = useUserSession()
+
+const links = [
+  { label: 'Docs', to: '/docs' },
+  { label: 'Blog', to: '/blog' }
+]
+</script>
+
+<template>
+  <UHeader title="ACME" :links="links">
+    <template #right>
+      <ClientOnly>
+        <UButton v-if="loggedIn" to="/profile">{{ user.name }}</UButton>
+        <UButton v-else to="/login">Login</UButton>
+        <template #fallback>
+          <!-- Display loading state -->
+          <UButton :loading="true" />
+        </template>
+      </ClientOnly>
+  </template>
+</template>
+```