feat(nuxt): app.config with hmr and reactivity support (#6333)

Co-authored-by: Daniel Roe <[email protected]>

Author: pi0

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)
+```
+
+<!-- TODO: Document module author for extension -->
+
+### 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 {}
+```

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"}

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"}

examples/advanced/config-extends/app.config.ts

@@ -0,0 +1,5 @@
+export default defineAppConfig({
+  foo: 'user',
+  bar: 'user',
+  baz: 'base'
+})

examples/advanced/config-extends/base/app.config.ts

@@ -0,0 +1,4 @@
+export default defineAppConfig({
+  bar: 'base',
+  baz: 'base'
+})

examples/advanced/config-extends/pages/index.vue

@@ -1,12 +1,15 @@
 <script setup>
 const themeConfig = useRuntimeConfig().theme
+const appConfig = useAppConfig()
 const foo = useFoo()
 const bar = getBar()
 </script>
 
 <template>
   <NuxtExampleLayout example="advanced/config-extends">
-    theme runtimeConfig
+    appConfig:
+    <pre>{{ JSON.stringify(appConfig, null, 2) }}</pre>
+    runtimeConfig:
     <pre>{{ JSON.stringify(themeConfig, null, 2) }}</pre>
     <BaseButton>Base Button</BaseButton>
     <FancyButton>Fancy Button</FancyButton>

packages/nuxi/src/commands/dev.ts

@@ -132,7 +132,7 @@ export default defineNuxtCommand({
           dLoad(true, `Directory \`${relativePath}/\` ${event === 'addDir' ? 'created' : 'removed'}`)
         }
       } else if (isFileChange) {
-        if (file.match(/(app|error)\.(js|ts|mjs|jsx|tsx|vue)$/)) {
+        if (file.match(/(app|error|app\.config)\.(js|ts|mjs|jsx|tsx|vue)$/)) {
           dLoad(true, `\`${relativePath}\` ${event === 'add' ? 'created' : 'removed'}`)
         }
       }

packages/nuxt/src/app/config.ts

@@ -0,0 +1,48 @@
+import type { AppConfig } from '@nuxt/schema'
+import { reactive } from 'vue'
+import { useNuxtApp } from './nuxt'
+// @ts-ignore
+import __appConfig from '#build/app.config.mjs'
+
+// Workaround for vite HMR with virtual modules
+export const _getAppConfig = () => __appConfig as AppConfig
+
+export function useAppConfig (): AppConfig {
+  const nuxtApp = useNuxtApp()
+  if (!nuxtApp._appConfig) {
+    nuxtApp._appConfig = reactive(__appConfig) as AppConfig
+  }
+  return nuxtApp._appConfig
+}
+
+// HMR Support
+if (process.dev) {
+  function applyHMR (newConfig: AppConfig) {
+    const appConfig = useAppConfig()
+    if (newConfig && appConfig) {
+      for (const key in newConfig) {
+        (appConfig as any)[key] = (newConfig as any)[key]
+      }
+      for (const key in appConfig) {
+        if (!(key in newConfig)) {
+          delete (appConfig as any)[key]
+        }
+      }
+    }
+  }
+
+  // Vite
+  if (import.meta.hot) {
+    import.meta.hot.accept((newModule) => {
+      const newConfig = newModule._getAppConfig()
+      applyHMR(newConfig)
+    })
+  }
+
+  // Webpack
+  if (import.meta.webpackHot) {
+    import.meta.webpackHot.accept('#build/app.config.mjs', () => {
+      applyHMR(__appConfig)
+    })
+  }
+}

packages/nuxt/src/app/index.ts

@@ -3,6 +3,7 @@
 export * from './nuxt'
 export * from './composables'
 export * from './components'
+export * from './config'
 
 // eslint-disable-next-line import/no-restricted-paths
 export type { PageMeta } from '../pages/runtime'

packages/nuxt/src/app/nuxt.ts

@@ -2,7 +2,7 @@
 import { getCurrentInstance, reactive } from 'vue'
 import type { App, onErrorCaptured, VNode } from 'vue'
 import { createHooks, Hookable } from 'hookable'
-import type { RuntimeConfig } from '@nuxt/schema'
+import type { RuntimeConfig, AppConfigInput } from '@nuxt/schema'
 import { getContext } from 'unctx'
 import type { SSRContext } from 'vue-bundle-renderer/runtime'
 import type { CompatibilityEvent } from 'h3'
@@ -281,3 +281,7 @@ export function useRuntimeConfig (): RuntimeConfig {
 function defineGetter<K extends string | number | symbol, V> (obj: Record<K, V>, key: K, val: V) {
   Object.defineProperty(obj, key, { get: () => val })
 }
+
+export function defineAppConfig<C extends AppConfigInput> (config: C): C {
+  return config
+}