diff --git a/docs/content/2.guide/2.features/10.app-config.md b/docs/content/2.guide/2.features/10.app-config.md new file mode 100644 index 00000000000..c3544181514 --- /dev/null +++ b/docs/content/2.guide/2.features/10.app-config.md @@ -0,0 +1,55 @@ +# App Config + +::StabilityEdge +:: + +Nuxt 3 provides an `app.config` config file to expose reactive configuration within your application with the ability to update it at runtime within lifecycle or using a nuxt plugin and editing it with HMR (hot-module-replacement). + +::alert{type=warning} +Do not put any secret values inside `app.config` file. It is exposed to the user client bundle. +:: + +## Defining App Config + +To expose config and environment variables to the rest of your app, you will need to define configuration in `app.config` file. + +**Example:** + +```ts [app.config.ts] +export default defineAppConfig({ + theme: { + primaryColor: '#ababab' + } +}) +``` + +When adding `theme` to the `app.config`, Nuxt uses Vite or Webpack to bundle the code. We can universally access `theme` in both server and browser using [useAppConfig](/api/composables/use-app-config) composable. + +```js +const appConfig = useAppConfig() + +console.log(appConfig.theme) +``` + + + +### Manually Typing App Config + +Nuxt tries to automatically generate a typescript interface from provided app config. + +It is also possible to type app config manually: + +```ts [index.d.ts] +declare module '@nuxt/schema' { + interface AppConfig { + /** Theme configuration */ + theme: { + /** Primary app color */ + primaryColor: string + } + } +} + +// It is always important to ensure you import/export something when augmenting a type +export {} +``` diff --git a/docs/content/2.guide/3.directory-structure/16.app.config.md b/docs/content/2.guide/3.directory-structure/16.app.config.md new file mode 100644 index 00000000000..61bfbf510da --- /dev/null +++ b/docs/content/2.guide/3.directory-structure/16.app.config.md @@ -0,0 +1,24 @@ +--- +icon: IconFile +title: app.config.ts +head.title: Nuxt App Config +--- + +# Nuxt App Config + +::StabilityEdge +:: + +You can easily provide runtime app configuration using `app.config.ts` file. It can have either of `.ts`, `.js`, or `.mjs` extensions. + +```ts [app.config.ts] +export default defineAppConfig({ + foo: 'bar' +}) +``` + +::alert{type=warning} +Do not put any secret values inside `app.config` file. It is exposed to the user client bundle. +:: + +::ReadMore{link="/guide/features/app-config"} diff --git a/docs/content/3.api/1.composables/use-app-config.md b/docs/content/3.api/1.composables/use-app-config.md new file mode 100644 index 00000000000..72c0dd5033f --- /dev/null +++ b/docs/content/3.api/1.composables/use-app-config.md @@ -0,0 +1,16 @@ +# `useAppConfig` + +::StabilityEdge +:: + +Access [app config](/guide/features/app-config): + +**Usage:** + +```js +const appConfig = useAppConfig() + +console.log(appConfig) +``` + +::ReadMore{link="/guide/features/app-config"} diff --git a/examples/advanced/config-extends/app.config.ts b/examples/advanced/config-extends/app.config.ts new file mode 100644 index 00000000000..909ae0dc97f --- /dev/null +++ b/examples/advanced/config-extends/app.config.ts @@ -0,0 +1,5 @@ +export default defineAppConfig({ + foo: 'user', + bar: 'user', + baz: 'base' +}) diff --git a/examples/advanced/config-extends/base/app.config.ts b/examples/advanced/config-extends/base/app.config.ts new file mode 100644 index 00000000000..b94ce0b0b05 --- /dev/null +++ b/examples/advanced/config-extends/base/app.config.ts @@ -0,0 +1,4 @@ +export default defineAppConfig({ + bar: 'base', + baz: 'base' +}) diff --git a/examples/advanced/config-extends/pages/index.vue b/examples/advanced/config-extends/pages/index.vue index 549b1d0dc59..1c754df8549 100644 --- a/examples/advanced/config-extends/pages/index.vue +++ b/examples/advanced/config-extends/pages/index.vue @@ -1,12 +1,15 @@