From 9f1ac4f201e41256d95bb447a2f7a9dbd587f440 Mon Sep 17 00:00:00 2001
From: Krutie Patel <krutie.patel@gmail.com>
Date: Mon, 12 Sep 2022 20:29:42 +1000
Subject: [PATCH] docs(api): add `useRuntimeConfig` page (#7406)

Co-authored-by: Pooya Parsa <pooya@pi0.io>
Co-authored-by: Daniel Roe <daniel@roe.dev>
---
 .../3.api/1.composables/use-runtime-config.md | 139 ++++++++++++++++++
 1 file changed, 139 insertions(+)
 create mode 100644 docs/content/3.api/1.composables/use-runtime-config.md

diff --git a/docs/content/3.api/1.composables/use-runtime-config.md b/docs/content/3.api/1.composables/use-runtime-config.md
new file mode 100644
index 0000000000..578f9116b4
--- /dev/null
+++ b/docs/content/3.api/1.composables/use-runtime-config.md
@@ -0,0 +1,139 @@
+# `useRuntimeConfig`
+
+The `useRuntimeConfig` composable is used to expose config variables within your app.
+
+## Usage
+
+```vue [app.vue]
+<script setup lang="ts">
+const config = useRuntimeConfig()
+</script>
+```
+
+```ts [server/api/foo.ts]
+export default defineEventHandler((event) => {
+  const config = useRuntimeConfig()
+})
+```
+
+## Define Runtime Config
+
+The example below shows how to set a public API base URL and a secret API token that is only accessible on the server.
+
+We should always define `runtimeConfig` variables inside `nuxt.config`.
+
+```ts [nuxt.config.ts]
+export default defineNuxtConfig({
+  runtimeConfig: {
+    // Private keys are only available on the server
+    apiSecret: '123',
+
+    // Public keys that are exposed to the client
+    public: {
+      apiBase: process.env.NUXT_PUBLIC_API_BASE || '/api'
+    }
+  }
+})
+```
+
+::alert
+Variables that need to be accessible on the server are added directly inside `runtimeConfig`. Variables that need to be accessible on both the client and the server are defined in `runtimeConfig.public`.
+::
+
+::ReadMore{link="/guide/features/runtime-config"}
+::
+
+## Acess Runtime Config
+
+To access runtime config, we can use `useRuntimeConfig()` composable:
+
+```ts [server/api/test.ts]
+export default async () => {
+  const config = useRuntimeConfig()
+
+  // Access public variables
+  const result = await $fetch(`/test`, {
+    baseURL: config.public.apiBase,
+    headers: {
+      // Access a private variable (only available on the server)
+      Authorization: `Bearer ${config.apiSecret}`
+    }
+  })
+  return result
+}
+```
+
+In this example, since `apiBase` is defined within the `public` namespace, it is universally accessible on both server and client-side, while `apiSecret` **is only accessible on the server-side**.
+
+## Environment Variables
+
+It is possible to update runtime config values using a matching environment variable name prefixed with `NUXT_`.
+
+::ReadMore{link="/guide/features/runtime-config"}
+::
+
+### Using the `.env` File
+
+We can set the environment variables inside the `.env` file to make them accessible during **development** and **build/generate**.
+
+``` [.env]
+NUXT_PUBLIC_API_BASE_URL = "https://api.localhost:5555"
+NUXT_APP_SECRET = "123"
+```
+
+::alert{type=info}
+Any environment variables set within `.env` file are accessed using `process.env` in the Nuxt app during **development** and **build/generate**.
+::
+
+::alert{type=warning}
+In **production runtime**, you should use platform environment variables and `.env` is not used.
+::
+
+::alert{type=warning}
+When using git, make sure to add `.env` to the `.gitignore` file to avoid leaking secrets to the git history.
+::
+
+## `app` namespace
+
+Nuxt uses `app` namespace in runtime-config with keys including `baseURL` and `cdnURL`. You can customize their values at runtime by setting environment variables.
+
+::alert{type=info}
+This is a reserved namespace. You should not introduce additional keys inside `app`.
+::
+
+### `app.baseURL`
+
+By default, the `baseURL` is set to `'/'`.
+
+However, the `baseURL` can be updated at runtime by setting the `NUXT_APP_BASE_URL` as an environment variable.
+
+Then, you can access this new base URL using `config.app.baseURL`:
+
+```ts [/plugins/my-plugin.ts]
+export default defineNuxtPlugin((NuxtApp) => {
+  const config = useRuntimeConfig()
+
+  // Access baseURL universally
+  const baseURL = config.app.baseURL
+})
+```
+
+### `app.cdnURL`
+
+This example shows how to set a custom CDN url and access them using `useRuntimeConfig()`.
+
+You can use a custom CDN for serving static assets inside `.output/public` using the `NUXT_APP_CDN_URL` environment variable.
+
+And then access the new CDN url using `config.app.cdnURL`.
+
+```ts [server/api/foo.ts]
+export default defineEventHandler((event) => {
+  const config = useRuntimeConfig()
+
+  // Access cdnURL universally
+  const cdnURL = config.app.cdnURL
+})
+```
+
+::ReadMore{link="/guide/features/runtime-config"}
+::