Nuxt/docs/content/3.docs/1.usage/5.runtime-config.md

113 lines
3.4 KiB
Markdown
Raw Normal View History

# Runtime Config
2021-11-21 12:31:44 +00:00
Nuxt provides an API to define the runtime config within your application and API routes.
## Exposing runtime config
2021-11-21 12:31:44 +00:00
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 either the [`privateRuntimeConfig` or `publicRuntimeConfig` options](/docs/directory-structure/nuxt.config#privateruntimeconfig) (based on whether you want it to be accessible on the client-side part of your app or not).
**Example:**
```ts [nuxt.config.ts]
export default defineNuxtConfig({
2021-11-21 12:31:44 +00:00
publicRuntimeConfig: {
API_BASE: '/api'
},
privateRuntimeConfig: {
API_SECRET: '123'
}
})
```
2021-11-21 12:31:44 +00:00
When adding `API_BASE` to the `publicRuntimeConfig`, Nuxt adds it to the pages' payload. This way we can universally access `API_BASE` in both server and browser.
### 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).
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.
**Example:**
```sh [.env]
BASE_URL=https://nuxtjs.org
API_SECRET=api_secret_token
```
```ts [nuxt.config.ts]
export default defineNuxtConfig({
publicRuntimeConfig: {
BASE_URL: process.env.BASE_URL
},
privateRuntimeConfig: {
API_SECRET: process.env.API_SECRET
}
})
```
**💡 Tip:** While it is not necessary, by using identical runtime config names as env variables, you can easily override them in production using platform environment variables.
## 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 client side and server side:
2021-11-21 12:31:44 +00:00
- On client side, only `publicRuntimeConfig` is available and the object is both writable and reactive.
- On server side, both `publicRuntimeConfig` and `privateRuntimeConfig` are merged and the object is read-only to avoid context sharing.
```vue
<template>
<div>
<div>Token: {{ config.API_AUTH_TOKEN }}</div>
</div>
</template>
<script setup>
const config = useRuntimeConfig()
</script>
```
2021-11-21 12:31:44 +00:00
**🛑 Security note:** Never use example above if `API_AUTH_TOKEN` is a private config. Even if you use `privateRuntimeConfig`, you still have to be careful that you do not expose such config to either payload or html!
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
::
### API routes
Within the API routes, you can access runtime config by directly importing from virtual `#config`.
```ts
import config from '#config'
export default async () => {
const result = await $fetch('https://my.api.com/test', {
headers: {
Authorization: `Bearer ${config.API_AUTH_TOKEN}`
}
})
return result
}
```
### Typing runtime config
Currently it is possible to manually type your runtime config.
```ts [index.d.ts]
declare module '@nuxt/kit' {
interface PublicRuntimeConfig {
testConfig: string
}
interface PrivateRuntimeConfig {
token: string
}
}
// It is always important to ensure you import/export something when augmenting a type
export {}
```