docs: server updates/introduction (#205)

Co-authored-by: Pooya Parsa <pyapar@gmail.com>

docs/content/3.server/1.intro.md

@@ -0,0 +1,41 @@
+# Overview
+
+Nuxt3 is powered by a new server engine, code-named Nitro. It has:
+
+- Cross-platform support for Node.js, browser, service-worker targets and more
+- Serverless support out-of-the-box
+- API routes support
+- Automatic code-splitting and async-loaded chunks
+- Hybrid mode for static + serverless sites
+- A development mode with hot module reloading
+
+In addition it is backwards compatible with Nuxt2 via [a compatibility module](/server/compat).
+
+## API Layer
+
+Server [API endpoints](/server/api) and [Middleware](/server/middleware) are added by Nitro that internally uses [h3](https://github.com/unjs/h3).
+
+There are a number of key features, including:
+
+* Handlers can directly return objects/arrays for an automatically-handled JSON response
+* Handlers can return promises, which will be awaited (`res.end()` and `next()` are also supported)
+* Helper functions for body parsing, cookie handling, redirects, headers and more
+
+ Check out [the h3 docs](https://github.com/unjs/h3) for more information.
+
+## Direct API calls
+
+Nitro allows 'direct' calling of routes via the globally-available `$fetch` helper. This will make an API call to the server if run on the browser, but will simply call the relevant function if run on the server, saving an additional API call.
+
+`$fetch` API is using [ohmyfetch](https://github.com/unjs/ohmyfetch), with key features including:
+
+* Automatic parsing of JSON responses (with access to raw response if needed)
+* Request body and params are automatically handled, with correct `Content-Type` headers being added
+
+For more information on `$fetch` features, check out [ohmyfetch](https://github.com/unjs/ohmyfetch).
+
+## Standalone Server
+
+Nitro produces a standalone server dist that is independent of `node_modules`.
+
+The server in Nuxt2 is not standalone, but requires part of nuxt core to be involved running `nuxt start` (with the `nuxt-start` or `nuxt` distributions) or custom programmatic usage, which was fragile and prone to breakage and not suitable for serverless and service-worker environments.

docs/content/3.server/2.api.md

@@ -2,21 +2,21 @@
 
 Nuxt will automatically read in any files in the `~/server/api` directory to create API endpoints.
 
-Each file should export a default function that handles api requests. It can return a promise or JSON data directly or use `res.end()`. API routes are powered by [h3](https://github.com/unjs/h3).
+Each file should export a default function that handles api requests. It can return a promise or JSON data directly (or use `res.end()`).
 
-**Example:** Hello world
+## Examples
+
+### Hello world
 
 ```js [server/api/hello.ts]
-export default async (req, res) => 'Hello World'
+export default (req, res) => 'Hello World'
 ```
 
 See result on http://localhost:3000/api/hello
 
-**Example:** An async function
+### Async function
 
 ```js [server/api/async.ts]
-import express from 'express'
-
 export default async (req, res) => {
   await someAsyncFunction()
 
@@ -28,8 +28,10 @@ export default async (req, res) => {
 
 **Example:** Using Node.js style
 
-```js [server/api/node.ts]
+```ts [server/api/node.ts]
-export default async (req, res) => {
+import type { IncomingMessage, ServerResponse } from 'http'
+
+export default async (req: IncomingMessage, res: ServerResponse) => {
   res.statusCode = 200
   res.end('Works!')
 }

docs/content/3.server/2.middleware.md

@@ -1,11 +0,0 @@
-# Server Middleware
-
-Nuxt will automatically read in any files in the `~/server/middleware` to create server middleware for your project. (These files will be run on every request, unliked [API routes](./api) that are mapped to their own routes.)
-
-Each file should export a default function that will handle a request.
-
-```js
-export default async (req, res) => {
-  req.someValue = true
-}
-```

docs/content/3.server/3.middleware.md

@@ -0,0 +1,23 @@
+# Server Middleware
+
+Nuxt will automatically read in any files in the `~/server/middleware` to create server middleware for your project.
+
+These files will be run on every request, unlike [API routes](./api) that are mapped to their own routes. This is typically so you can add a common header to all responses, log responses or modify the incoming request object for use later on in the request chain.
+
+Each file should export a default function that will handle a request.
+
+```js
+export default async (req, res) => {
+  req.someValue = true
+}
+```
+
+There is nothing different about the `req`/`res` objects, so typing them is straightforward.
+
+```ts
+import type { IncomingMessage, ServerResponse } from 'http'
+
+export default async (req: IncomingMessage, res: ServerResponse) => {
+  req.someValue = true
+}
+```

docs/content/7.bridge/1.nitro.md

@@ -0,0 +1,31 @@
+# Nitro
+
+> It is possible to use the Nuxt3 rendering engine (Nitro) with Nuxt2 via a compatibility module.
+
+1. Install `@nuxt/nitro` as a devDependency:
+
+   ```bash
+   yarn add --dev @nuxt/nitro
+   ```
+
+1. Add `@nuxt/nitro/compat` to `buildModules` inside `nuxt.config`:
+
+   ```ts [nuxt.config.js]
+   export default {
+     buildModules: [
+       '@nuxt/nitro/compat'
+     ]
+   }
+   ```
+
+1. If you have selected `target: 'static'` in your `nuxt.config`, update the `build` script in package.json to be `nuxt generate`:
+
+   ```json [package.json]
+   {
+     "scripts": {
+       "build": "nuxt generate"
+     }
+   }
+   ```
+
+Now, when you build your project, Nitro will generate an optimized server bundle for fast, next-generation edge rendering.

docs/content/7.compatibility/1.nuxt3.md

@@ -1 +0,0 @@
-# Nuxt3

docs/content/7.compatibility/2.nitro.md

@@ -1 +0,0 @@
-# Nitro Compat