From 8680426eb7090f3c4cec3bf4aada4b2b1a7fd74b Mon Sep 17 00:00:00 2001 From: Pooya Parsa Date: Mon, 12 Sep 2022 12:07:50 +0200 Subject: [PATCH] update use-runtime-config --- .../3.api/1.composables/use-runtime-config.md | 156 +++++++++++------- 1 file changed, 92 insertions(+), 64 deletions(-) diff --git a/docs/content/3.api/1.composables/use-runtime-config.md b/docs/content/3.api/1.composables/use-runtime-config.md index 8593e23d860..37fbbe74d2d 100644 --- a/docs/content/3.api/1.composables/use-runtime-config.md +++ b/docs/content/3.api/1.composables/use-runtime-config.md @@ -4,109 +4,137 @@ ## Usage +```vue [app.vue] + +``` + ```ts [server/api/foo.ts] export default defineEventHandler((event) => { const config = useRuntimeConfig() }) ``` -`useRuntimeConfig` provides an `app` object with `baseURL` and `cdnURL` out of the box. However, Nuxt provides the ability to update their values at runtime by setting environment variables in the `.env` file. +## Define Runtime Config -## Examples +This example below shows how to set base API endpoint URL for public access and secret API token for only accessible on the server-side. -### Update base URL +We should always define `runtimeConfig` variables inside `nuxt.config`. -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 in the `.env` file of your Nuxt App. - -This is particularly useful when there are multiple environments, such as `development`, `test` and `production`, and they share similar variable names with slightly different values. +```ts [/nuxt.config.ts] +export default defineNuxtConfig({ + runtimeConfig: { + // The private keys are only available on server-side + apiSecret: '123', -``` [.env] -NUXT_APP_BASE_URL = 'https://localhost:5555' + // The public keys are exposed to the client-side + public: { + apiBase: process.env.API_BASE_URL || '/api' + } + } +}) ``` -Then, you can access this new base URL using `config.app.baseURL`. +::alert +Variables needed to be accessable from server-side are added directly inside `runtimeConfig: {}`. +Variables needed to be accessable from both client-side and server-side are defined in `runtimeConfig.public: {}.`. +:: + +::ReadMore{link="/guide/features/runtime-config"} +:: -```ts [/plugins/my-plugin.ts] -export default defineNuxtPlugin((NuxtApp) => { +## Acess Runtime Config + +To access runtime config, we can use `useRuntimeConfig()` composable: + +```ts [server/api/test.ts] +export default async () => { const config = useRuntimeConfig() - // Access baseURL universally - const baseURL = config.app.baseURL -}) + // Access public variables + const result = await $fetch(`/test`, { + baseURL: config.public.apiBase, + headers: { + // Access private variable (only available on server-side) + Authorization: `Bearer ${config.apiSecret}` + } + }) + return result +} ``` -### Set CDN URL +In this example, since `apiBase` is defined within the `public` namespace, it is universally accessible on both server and client-side, while an `apiSecret` **is only accessible on the server-side**. -This example shows how to set a custom CDN url and access them using `useRuntimeConfig()`. +## Environment Variables -By default, the `public/` folder is treated as a static content provider. But you can change that by providing your own CDN url through the environment variable. +It is possible to update runtime config values using matching environment variable name prefixed with `NUXT_`. -First, you set the environment variable `NUXT_APP_CDN_URL` in the `.env` file. +::ReadMore{link="/guide/features/runtime-config"} +:: + +### Using the `.env` File + +We can set the environment variables in the `.env` file to make them accessable during **development** and **build/generate**. ``` [.env] -NUXT_APP_CDN_URL = 'https://cdn.localhost:5555' +NUXT_PUBLIC_API_BASE_URL = "https://api.localhost:5555" +NUXT_APR_SECRET = "123" ``` -And then access the new CDN url using `config.app.cdnURL`. +::alert{type=info} +Any environment variables set within `.env` file are accessed using `process.env` in the Nuxt app during **development** and **build/generate**. +:: -```ts [server/api/foo.ts] -export default defineEventHandler((event) => { - const config = useRuntimeConfig() - - // Access cdnURL universally - const cdnURL = config.app.cdnURL -}) -``` +::alert{type=warning} +In **production runtime**, you should use platform environment variables and `.env` is not used. +:: -### Private and public variables +::alert{type=warning} +When using git, make sure to add `.env` to the `.gitignore` file to avoid leaking secrets to the git history. +:: -This example below shows how to set base API endpoint url for public access and secret API token for only accessible on the server-side. +## `app` namespace -- First, you set the environment variable `API_BASE_URL` in the `.env` file. +Nuxt uses `app` namespace in runtime-config with keys including `baseURL` and `cdnURL`. You can customize their values at runtime by setting environment variables. -``` [.env] -API_BASE_URL = 'https://api.localhost:5555' -``` +::alert{type=info} +This is a reserved namespace. You cannot not introduce additional keys inside `app`. +:: -- Then access `API_BASE_URL` within the `nuxt.config` file. +### `app.baseURL` -Any environment variables set within `.env` file are accessed using `process.env` in the Nuxt app. +By default, the `baseURL` is set to `'/'`. -Variables needed to be set during runtime are defined in `runtimeConfig.public: {}`, while the variables needed during build-time are added directly inside `runtimeConfig: {}`. +However, the `baseURL` can be updated at runtime by setting the `NUXT_APP_BASE_URL` as an environment variable. -```ts [/nuxt.config.ts] -export default defineNuxtConfig({ - runtimeConfig: { - // The private keys are only available on server-side - apiSecret: '123', - - // The public keys are exposed to the client-side - public: { - apiBase: process.env.API_BASE_URL - } - } +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 }) ``` -- And finally access both public and private variables on server-side as below. +### `app.cdnURL` -```ts [server/api/test.ts] -export default async () => { +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 in `.output/public` from using environment variable `NUXT_APP_CDN_URL`. + +And then access the new CDN url using `config.app.cdnURL`. + +```ts [server/api/foo.ts] +export default defineEventHandler((event) => { const config = useRuntimeConfig() - - // Access public variables - const result = await $fetch(`${config.public.apiBase}/test`, { - headers: { - // Access private variable - Authorization: `Bearer ${config.apiSecret}` - } - }) - return result -} -``` -In this example, since `apiBase` is defined within `public:{}` key, it is universally accessible on both server and client-side, while an `apiSecret` is only accessible on the server-side. + // Access cdnURL universally + const cdnURL = config.app.cdnURL +}) +``` ::ReadMore{link="/guide/features/runtime-config"} ::