From d53cc604db956420f237cf8567222406a01fa844 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?S=C3=A9bastien=20Chopin?= <seb@nuxtlabs.com>
Date: Tue, 16 May 2023 13:16:09 +0200
Subject: [PATCH] docs: server directory improvements

---
 .../2.guide/2.directory-structure/1.server.md | 61 +++++++++++++------
 1 file changed, 44 insertions(+), 17 deletions(-)

diff --git a/docs/2.guide/2.directory-structure/1.server.md b/docs/2.guide/2.directory-structure/1.server.md
index 36927a446f..8b56091283 100644
--- a/docs/2.guide/2.directory-structure/1.server.md
+++ b/docs/2.guide/2.directory-structure/1.server.md
@@ -7,33 +7,46 @@ description: The server/ directory is used to register API and server handlers t
 
 # Server Directory
 
-Nuxt automatically scans files inside the `~/server/api`, `~/server/routes`, and `~/server/middleware` directories to register API and server handlers with HMR support.
+Nuxt automatically scans files inside these directories to register API and server handlers with HMR support:
+- `~/server/api`
+- `~/server/routes`
+- `~/server/middleware` 
 
-Each file should export a default function defined with `defineEventHandler()`.
+Each file should export a default function defined with `defineEventHandler()` or `eventHandler()` (alias).
 
-The handler can directly return JSON data, a `Promise` or use `event.node.res.end()` to send response.
+The handler can directly return JSON data, a `Promise` or use `event.node.res.end()` to send a response.
 
-::ReadMore{link="https://nitro.unjs.io/guide/routing" title="Nitro Route Handling Docs"}
-::
-
-## Example
-
-Create a new file in `server/api/hello.ts`:
+**Example:** Create the `/api/hello` route with `server/api/hello.ts` file:
 
 ```ts [server/api/hello.ts]
 export default defineEventHandler((event) => {
   return {
-    api: 'works'
+    hello: 'world'
   }
 })
 ```
 
-You can now universally call this API using `await $fetch('/api/hello')`.
+You can now universally call this API in your pages and components:
+
+```vue [pages/index.vue]
+<script setup>
+const { data } = await useFetch('/api/hello')
+</script>
+
+<template>
+  <pre>{{ data }}</pre>
+</template>
+```
+
+Note that [h3 utilities](https://github.com/unjs/h3#utilities) are auto-imported.
+
+:ReadMore{link="https://nitro.unjs.io/guide/routing" title="Nitro Route Handling Docs"}
 
 ## Server Routes
 
 Files inside the `~/server/api` are automatically prefixed with `/api` in their route.
-For adding server routes without `/api` prefix, you can instead put them into `~/server/routes` directory.
+
+To add server routes without `/api` prefix, put them into `~/server/routes` directory.
 
 **Example:**
 
@@ -57,7 +70,7 @@ Middleware handlers should not return anything (nor close or respond to the requ
 
 ```ts [server/middleware/log.ts]
 export default defineEventHandler((event) => {
-  console.log('New request: ' + event.node.req.url)
+  console.log('New request: ' + getRequestURL(event))
 })
 ```
 
@@ -79,18 +92,32 @@ export default defineNitroPlugin((nitroApp) => {
 })
 ```
 
-::ReadMore{link="https://nitro.unjs.io/guide/plugins" title="Nitro Plugins"}
-::
+:ReadMore{link="https://nitro.unjs.io/guide/plugins" title="Nitro Plugins"}
 
 ## Server Utilities
 
 Server routes are powered by [unjs/h3](https://github.com/unjs/h3) which comes with a handy set of helpers.
 
-::ReadMore{link="https://www.jsdocs.io/package/h3#package-index-functions" title="Available H3 Request Helpers"}
-::
+:ReadMore{link="https://www.jsdocs.io/package/h3#package-index-functions" title="Available H3 Request Helpers"}
 
 You can add more helpers yourself inside the `~/server/utils` directory.
 
+## Server Types
+
+::alert{type="info"}
+This feature is available from Nuxt >= 3.5
+::
+
+To improve clarity within your IDE between the auto-imports from 'nitro' and 'vue', you can add a `~/server/tsconfig.json` with the following content:
+
+```json [server/tsconfig.json]
+{
+  "extends": "../.nuxt/tsconfig.server.json"
+}
+```
+
+Although right now these values won't be respected when type checking (`nuxi typecheck`), you should get better type hints in your IDE.
+
 ## Usage Examples
 
 ### Matching Route Parameters