docs: update the storage page (#2086)

docs/content/1.guide/4.storage.md

@@ -8,22 +8,33 @@ Nitro provides a built-in storage layer that can abstract filesystem or database
 
 `useStorage()` is an instance of [createStorage](https://unstorage.unjs.io/getting-started/usage) using the [memory driver](https://unstorage.unjs.io/drivers/memory).
 
-**Example:** Simple (in memory) operations
+By default, Nitro will also mount the current directory using the filesystem driver, using a prefix and where each folder serve to extend the prefix.
 
-```js
+- Every file will be under the `root` base.
+- Every source file will be under the `src` base. (By default, `src` is the `root` base)
+
+## Usage
+
+To use the storage layer, you can use the `useStorage()` and call `getItem` to retrieve an item and `setItem` to set an item.
+
+```ts
 await useStorage().setItem('test:foo', { hello: 'world' })
 await useStorage().getItem('test:foo')
 
 // You can also specify the base in useStorage(base)
 await useStorage('test').setItem('foo', { hello: 'world' })
-await useStorage('test').getItem('foo')
+// `useStorage` and chained functions support a generic type to infer the return type
+await useStorage<{ hello: string }>('test').getItem('foo')
+await useStorage('test').getItem<{ hello: string }>('foo')
 ```
 
 See [Unstorage](https://unstorage.unjs.io/getting-started/usage) for detailed usage.
 
-## Mountpoints
+## Mount Points
 
-You can mount storage drivers using the `storage` option:
+You can mount storage drivers using the `storage` option in the [Nitro config](/guide/config) file.
+
+The key is the mount point name, and the value is the driver name and configuration. You can find the driver list on [unstorage documentation](https://unstorage.unjs.io/) with their configuration. You can mount multiple drivers.
 
 ::code-group
 ```ts [nitro.config.ts]
@@ -58,14 +69,13 @@ export default defineNuxtConfig({
 ```
 ::
 
+::alert{type="warning"}
+`cache` is a reserved mount point for the [cache layer](/guide/cache). Do not use it unless you want to overwrite the cache layer.
+::
 
 ### Runtime configuration
 
-In scenarios where the mount point configuration is not known until runtime, Nitro can dynamically add mount points during startup using [plugins](/guide/plugins):
-
-::alert{type="info"}
-This is a temporary workaround, with a better solution coming in the future! Keep a lookout on the GitHub issue [here](https://github.com/unjs/nitro/issues/1161#issuecomment-1511444675).
-::
+In scenarios where the mount point configuration is not known until runtime, Nitro can dynamically add mount points during startup using [plugins](/guide/plugins).
 
 ::code-group
 ```ts [plugins/storage.ts]
@@ -110,46 +120,15 @@ export default defineNuxtConfig({
 ```
 ::
 
+::alert{type="warning"}
+This is a temporary workaround, with a better solution coming in the future! Keep a lookout on the GitHub issue [here](https://github.com/unjs/nitro/issues/1161#issuecomment-1511444675).
+::
 
-Usage:
-
-```js
-await useStorage('redis').setItem('foo', { hello: 'world' })
-await useStorage('redis').getItem('foo')
-// or
-await useStorage().setItem('redis:foo', { hello: 'world' })
-await useStorage().getItem('redis:foo')
-```
-
-Usage with [generics](https://unstorage.unjs.io/getting-started/usage#generic-types):
-
-```ts
-await useStorage().getItem<string>('foo')
-// => string
-await useStorage<string>().getItem('foo')
-// => string
-
-await useStorage<string>().setItem('foo', 123) // ts error
-
-type Foo = { data: number }
-
-await useStorage().getItem<Foo>('foo')
-// => Foo
-```
-
-You can find the list of drivers on [unstorage documentation](https://unstorage.unjs.io/).
-
-In development, Nitro adds the `cache` mountpoint using the [FS driver](https://unstorage.unjs.io/drivers/fs) writting to `.nitro/cache` or `.nuxt/cache` if using [Nuxt](https://nuxt.com).
-
-```js
-await useStorage('cache').setItem('foo', { hello: 'world' })
-await useStorage('cache').getItem('foo')
-```
-
+## Development only Storage
 
-## Development storage
+You can use the `devStorage` key to overwrite the storage configuration during development. This is very useful when you use a database in production and want to use the filesystem in development.
 
-You can use the `devStorage` key to overwrite the storage configuration during development, very useful when you use a database in production and want to use the filesystem in development.
+In order to use the `devStorage` key, you need to use the `nitro dev` command and the key in the `storage` option must be the same as the production one.
 
 ::code-group
 ```ts [nitro.config.ts]
@@ -191,3 +170,5 @@ export default defineNuxtConfig({
 })
 ```
 ::
+
+You will also be able to access to a `build` namespace in the storage layer only during development. It contains file generated by Nitro.