Your module's setup receives a fully resolved options object. That object lives in Node, in a process that exits when the build finishes. Getting a value from there into a composable running in someone's browser is the single most-asked module question, because the answer forces you to reason about payload size, environment variables, tree-shaking and secrets all at once. There are exactly four channels, and the senior answer is the trade-off table, not the API call.

Know

• The four channels, and nothing else: runtimeConfig.public.<key>, private runtimeConfig.<key>, appConfig, and a generated template imported as #build/<filename>.

• Merge direction matters. Write your defaults under the user with defu: nuxt.options.runtimeConfig.public.toolkit = defu(nuxt.options.runtimeConfig.public.toolkit, { ... }). The consumer's own nuxt.config entry must keep winning, otherwise a module silently overwrites the value someone set deliberately.
• Read runtime config with useRuntimeConfig(), never from module-scope. On the server it is per-request (it is read off the event), so hoisting it into a module-level const inside a runtime file freezes the first request's values and leaks across requests.
• Environment variables are only picked up for keys that already exist. NUXT_PUBLIC_TOOLKIT_GREETING overrides runtimeConfig.public.toolkit.greeting only if that key was present at build time. A key you "forgot" to default is simply not overridable — which is why modules seed every option into runtime config even when the default is empty.
• appConfig is reactive. useAppConfig() returns a reactive object and updateAppConfig() can patch it at runtime, which is why it suits theme tokens. It is still baked into the bundle, so it cannot differ between staging and production from the same artifact.
• Templates are the escape hatch for size and shape. A generated module produces real JavaScript: the bundler tree-shakes what nobody imports, and nothing travels through the HTML payload. Anything large, derived, or that wants to be a function belongs here, not in runtime config.
• Type augmentation belongs in nuxt/schema. Declare PublicRuntimeConfig, RuntimeConfig and AppConfigInput so consumers get completion. @nuxt/module-builder emits this for you from the interfaces you export (see Templates and types); knowing the manual form still matters because you will read it in other modules' dist/types.d.mts.
• For a layers-first toolkit, the layer's nuxt.config is where the team's values live and the module is where the plumbing lives: the layer sets toolkit: { apiBase: … }, the module seeds it into runtime config so deploys can override it with NUXT_PUBLIC_TOOLKIT_API_BASE without a rebuild.

How it works

All four channels in one setup:

import { addImports, addTemplate, createResolver, defineNuxtModule } from '@nuxt/kit'
import { defu } from 'defu'

export interface ModuleOptions {
  apiBase: string
  apiToken: string
  theme: 'default' | 'compact'
  features: string[]
}

export default defineNuxtModule<ModuleOptions>({
  meta: { name: 'nuxt-team-toolkit', configKey: 'toolkit' },
  defaults: { apiBase: 'https://api.internal', apiToken: '', theme: 'default', features: [] },
  setup (options, nuxt) {
    const { resolve } = createResolver(import.meta.url)

    // 1. public runtime config — reaches the browser, overridable with NUXT_PUBLIC_TOOLKIT_API_BASE
    nuxt.options.runtimeConfig.public.toolkit = defu(
      nuxt.options.runtimeConfig.public.toolkit as Partial<ModuleOptions>,
      { apiBase: options.apiBase },
    )

    // 2. private runtime config — server only, overridable with NUXT_TOOLKIT_API_TOKEN
    nuxt.options.runtimeConfig.toolkit = defu(
      nuxt.options.runtimeConfig.toolkit as Partial<ModuleOptions>,
      { apiToken: options.apiToken },
    )

    // 3. appConfig — reactive, bundled, same in every environment
    nuxt.options.appConfig.toolkit = defu(nuxt.options.appConfig.toolkit, { theme: options.theme })

    // 4. template — build-time code generation, tree-shakeable, never in the payload
    addTemplate({
      filename: 'toolkit/features.mjs',
      getContents: () => [
        `export const features = ${JSON.stringify(options.features)}`,
        `export const hasFeature = name => features.includes(name)`,
      ].join('\n'),
    })

    addImports({ name: 'useToolkit', from: resolve('./runtime/app/composables/useToolkit') })
  },
})

The runtime side reads each channel with the right composable:

import { hasFeature } from '#build/toolkit/features.mjs'
import { useAppConfig, useRuntimeConfig } from '#imports'

export function useToolkit () {
  // per request on the server: must be called inside setup / a composable, never hoisted
  const { apiBase } = useRuntimeConfig().public.toolkit
  const { theme } = useAppConfig().toolkit
  return { apiBase, theme, hasFeature }
}

Types so consumers get completion in nuxt.config and in their components:

declare module 'nuxt/schema' {
  interface RuntimeConfig { toolkit: { apiToken: string } }
  interface PublicRuntimeConfig { toolkit: { apiBase: string } }
  interface AppConfigInput { toolkit?: { theme?: 'default' | 'compact' } }
}

Exercise

Be able to say