Nuxt/docs/content/2.guide/2.features/10.runtime-config.md

144 lines
4.2 KiB
Markdown
Raw Normal View History

# Runtime Config
Nuxt provides a runtime config API to expose config within your application and server routes with the ability to update them at runtime using environment variables.
## Exposing runtime config
To expose config and environment variables to the rest of your app, you will need to define runtime configuration in your `nuxt.config` file, using the [`runtimeConfig` option](/guide/directory-structure/nuxt.config#runtimeconfig).
**Example:**
```ts [nuxt.config.ts]
export default defineNuxtConfig({
runtimeConfig: {
// The private keys which are only available within server-side
apiSecret: '123',
// Keys within public, will be also exposed to the client-side
public: {
apiBase: '/api'
}
}
})
```
When adding `apiBase` to the `runtimeConfig.public`, Nuxt adds it to each page payload. We can universally access `apiBase` in both server and browser.
```js
const runtimeConfig = useRuntimeConfig()
console.log(runtimeConfig.apiSecret)
console.log(runtimeConfig.public.apiBase)
```
### Environment Variables
2021-11-21 12:31:44 +00:00
The most common way to provide configuration is by using [Environment Variables](https://medium.com/chingu/an-introduction-to-environment-variables-and-how-to-use-them-f602f66d15fa).
::alert{type=info}
Nuxt CLI has built-in [dotenv](https://github.com/motdotla/dotenv) support.
2021-11-21 12:31:44 +00:00
In addition to any process environment variables, if you have a `.env` file in your project root directory, it will be automatically loaded into `process.env` and accessible within your `nuxt.config` file and modules.
However, **after your project is built**, you are responsible for setting environment variables when you run the server - your `.env` file will not be read at this point.
::
Runtime config values are automatically replaced by matching environment variables at runtime. For this to work, you _must_ have a fallback value (which can just be an empty string) defined in your `nuxt.config`.
**Example:**
```sh [.env]
NUXT_API_SECRET=api_secret_token
NUXT_PUBLIC_API_BASE=https://nuxtjs.org
```
```ts [nuxt.config.ts]
export default defineNuxtConfig({
runtimeConfig: {
apiSecret: '',
public: {
apiBase: '', // Or a default value
}
},
})
```
## Accessing runtime config
### Vue app
Within the Vue part of your Nuxt app, you will need to call `useRuntimeConfig()` to access the runtime config.
**Note:** Behavior is different between the client-side and server-side:
- On the client-side, only keys in `public` are available, and the object is both writable and reactive.
The entire runtime config is available on the server-side, but it is read-only to avoid context sharing.
```vue
<template>
<div>
<div>Check developer console!</div>
</div>
</template>
<script setup>
const config = useRuntimeConfig()
console.log('Runtime config:', config)
if (process.server) {
console.log('API secret:', config.apiSecret)
}
</script>
```
**🛑 Security note:** Be careful not to expose runtime config keys to the client-side by either rendering them or passing them to `useState`.
2021-11-15 13:13:00 +00:00
::alert{icon=👉}
2021-11-21 12:31:44 +00:00
**`useRuntimeConfig` only works during `setup` or `Lifecycle Hooks`**.
2021-11-15 13:13:00 +00:00
::
### Plugins
If you want to use the runtime config within any (custom) plugin, you can use `useRuntimeConfig()` inside of your `defineNuxtPlugin` function.
For Example:
2022-01-25 12:19:40 +00:00
```ts
export default defineNuxtPlugin((nuxtApp) => {
const config = useRuntimeConfig()
console.log('API base URL:', config.public.apiBase)
});
```
### Server Routes
You can access runtime config within the server routes as well using `useRuntimeConfig`.
```ts
export default async () => {
const result = await $fetch('https://my.api.com/test', {
headers: {
Authorization: `Bearer ${useRuntimeConfig().apiSecret}`
}
})
return result
}
```
### Manually Typing Runtime Config
Nuxt tries to automatically generate a typescript interface from provided runtime config using [unjs/untyped](https://github.com/unjs/untyped)
It is also possible to type your runtime config manually:
```ts [index.d.ts]
declare module '@nuxt/schema' {
interface RuntimeConfig {
apiSecret: string
public: {
apiBase: string
}
}
}
// It is always important to ensure you import/export something when augmenting a type
export {}
```