mirror of https://github.com/nuxt/nuxt.git
129 lines
3.8 KiB
Markdown
129 lines
3.8 KiB
Markdown
# Runtime Config
|
|
|
|
Nuxt provides an API to define the runtime config within your application and API routes.
|
|
|
|
## 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 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({
|
|
publicRuntimeConfig: {
|
|
API_BASE: '/api'
|
|
},
|
|
privateRuntimeConfig: {
|
|
API_SECRET: '123'
|
|
}
|
|
})
|
|
```
|
|
|
|
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
|
|
|
|
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.
|
|
|
|
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:
|
|
|
|
- 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>
|
|
```
|
|
|
|
**🛑 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!
|
|
|
|
::alert{icon=👉}
|
|
**`useRuntimeConfig` only works during `setup` or `Lifecycle Hooks`**.
|
|
::
|
|
|
|
### Plugins
|
|
|
|
If you want to use the runtime confg within any (custom) plugin, you can use `useRuntimeConfig()` inside of your `defineNuxtPlugin` function.
|
|
|
|
For example:
|
|
|
|
```ts
|
|
export default defineNuxtPlugin((nuxtApp) => {
|
|
const config = useRuntimeConfig();
|
|
|
|
const url = process.server ? config.serverUrl : config.clientUrl;
|
|
|
|
// Do something with url & isServer.
|
|
});
|
|
```
|
|
|
|
### 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/schema' {
|
|
interface PublicRuntimeConfig {
|
|
testConfig: string
|
|
}
|
|
interface PrivateRuntimeConfig {
|
|
token: string
|
|
}
|
|
}
|
|
// It is always important to ensure you import/export something when augmenting a type
|
|
export {}
|
|
```
|