docs: update the configuration page

docs/content/1.guide/1.configuration.md

@@ -4,9 +4,7 @@ icon: ri:settings-3-line
 
 # Configuration
 
-You can customize your Nitro server with single configuration file: `nitro.config.ts`.
-
-All deployment providers are built on the same options API.
+You can customize your Nitro server with a single configuration file `nitro.config.ts`.
 
 If you are using [Nuxt](https://nuxt.com), use the `nitro` option in your Nuxt config.
 
@@ -25,9 +23,9 @@ export default defineNuxtConfig({
 ```
 ::
 
-Read all the [available options](/config) to configure Nitro.
+You can find all the [available options](/config) to configure Nitro.
 
-Nitro loads the configuration using [unjs/c12](https://github.com/unjs/c12), giving more  possibilities such as using `.nitrorc`.
+Nitro loads the configuration using [unjs/c12](https://github.com/unjs/c12), giving more  possibilities such as using `.nitrorc` file in current working directory or in the user's home directory.
 
 ::code-group
 ```bash [.nitrorc]
@@ -40,81 +38,82 @@ nitro.timing=true
 
 ## Runtime Configuration
 
-Nitro provides a runtime config API to expose configuration within your application, with the ability to update it at runtime by setting environment variables.
-
-To expose config and environment variables to the rest of your app, you will need to define runtime configuration in your configuration file.
+Nitro provides a runtime config API to expose configuration within your application, with the ability to update it at runtime by setting environment variables. This is useful when you want to expose different configuration values for different environments (e.g. development, staging, production). For example, you can use this to expose different API endpoints for different environments or to expose different feature flags.
 
-**Example:**
+First, you need to define the runtime config in your configuration file.
 
 ::code-group
 ```ts [nitro.config.ts]
 export default defineNitroConfig({
   runtimeConfig: {
-    helloThere: "foobar",
+    apiToken: "dev_token", // `dev_token` is the default value
   }
 })
 ```
 
 ```ts [nuxt.config.ts]
 export default defineNuxtConfig({
   runtimeConfig: {
-    helloThere: "foobar",
+    apiToken: "dev_token", // `dev_token` is the default value
   }
 })
 ```
 ::
 
-You can now access the runtime config using `useRuntimeConfig(event)`.
-
-**Example:**
+You can now access the runtime config using `useRuntimeConfig(event)`.  Use `useRuntimeConfig(event)` within event handlers and utilities and **avoid** calling it in ambient global contexts. This could lead to unexpected behavior such sharing the same runtime config across different requests.
 
 ::code-group
 ```ts [api/example.get.ts (nitro)]
 export default defineEventHandler((event) => {
-  return useRuntimeConfig(event).helloThere // foobar
+  return useRuntimeConfig(event).apiToken // Returns `dev_token`
 });
 ```
 
 ```ts [server/api/example.get.ts (nuxt)]
 export default defineEventHandler((event) => {
-  return useRuntimeConfig(event).helloThere // foobar
+  return useRuntimeConfig(event).apiToken // dev_token
 });
 ```
 ::
 
-::alert{type="info"}
-**Note:** Consider using `useRuntimeConfig(event)` within event handlers and utilities and avoid calling it in ambient global contexts.
-::
-
+`useRuntimeConfig(event)` is an auto-imported function. Read more about [auto-imports](/auto-imports).
 
-### Environment Variables
+### Local development
 
-Nitro supports defining environment variables using `.env` file in development (use platform variables for production).
+Finally, you can update the runtime config using environment variables. You can use a `.env` file in development and use platform variables in production (see below).
 
 Create an `.env` file in your project root:
 
 ```bash [.env]
-TEST="123"
+API_TOKEN="123"
 ```
 
-You can universally access environment variables using `import.meta.env.TEST` or `process.env.TEST`.
-
-::alert{type="info"}
-**Note:** Consider writing any logic that depends on environment variables within event handlers and utilities and avoid accessing and caching them in ambient global contexts.
-::
+Re-start the development server, fetch the `/api/example` endpoint and you should see `123` as the response instead of `dev_token`.
 
-### Update runtime config using environment variables
+Do not forget that you can still universally access environment variables using `import.meta.env` or `process.env` but avoid using them in ambiant global contexts to prevent unexpected behavior.
 
-The variables prefixed with `NITRO_` will be applied to runtime config, and they will override the variables defined within your `nitro.config.ts` file. (matching "camelCase" version).
+### Production
 
-**Example:**
+You can define variables in your production environment to update the runtime config. All variables must be prefixed with `NITRO_` to be applied to the runtime config. They will override the runtime config variables defined within your `nitro.config.ts` file.
 
 ::code-group
 ```bash [.env (nitro)]
-NITRO_HELLO_THERE="123"
+NITRO_API_TOKEN="123"
 ```
 
 ```bash [.env (nuxt)]
-NUXT_HELLO_THERE="123"
+NUXT_API_TOKEN="123"
 ```
 ::
+
+In runtime config, define key using camelCase. In environment variables, define key using snake_case and uppercase.
+
+```ts
+{
+  helloWorld: "foo"
+}
+```
+
+```bash
+NITRO_HELLO_WORLD="foo"
+```