Nuxt•4mo ago

Passing module options to runtime

When working on a Nuxt 3 module, what is the best way to expose the module's options (possibly defined in nuxt.config.ts) to parts of the runtime code such as components and server handlers?

Solution:

Jump to solution

7 Replies

kapa.ai•4mo ago

Hi @Dawit. I'm kapa.ai, your friendly support bot. I will try to answer your question by searching through the knowledge base. :wave: ---------------------- The recommended way to expose Nuxt 3 module options to your runtime code (such as components, plugins, or server handlers) is to add them to the Nuxt runtime config, specifically under the public key if they need to be accessible on the client side. This is because modules themselves are not part of the application runtime, so their options are not directly available at runtime. By merging your module options into runtimeConfig.public, you make them universally accessible via the useRuntimeConfig() composable. Here’s how you can do it in your module:

import { defineNuxtModule } from '@nuxt/kit'
import { defu } from 'defu'

export default defineNuxtModule({
  setup (options, nuxt) {
    nuxt.options.runtimeConfig.public.myModule = defu(
      nuxt.options.runtimeConfig.public.myModule,
      { foo: options.foo }
    )
  }
})

import { defineNuxtModule } from '@nuxt/kit'
import { defu } from 'defu'

export default defineNuxtModule({
  setup (options, nuxt) {
    nuxt.options.runtimeConfig.public.myModule = defu(
      nuxt.options.runtimeConfig.public.myModule,
      { foo: options.foo }
    )
  }
})

Then, in your runtime code (component, plugin, etc.), you can access the options like this:

const options = useRuntimeConfig().public.myModule

const options = useRuntimeConfig().public.myModule

Important:
- Only put non-sensitive options in public, as these will be exposed to the client bundle. - Use a merging utility like defu to avoid overwriting user-provided config. This approach is the recommended and documented way to expose module options to runtime in Nuxt 3 Altering Nuxt Configuration. ---------------------- Note: you can ask me a follow up question by @ mentioning me again :speech_balloon: ----------------------

kapa.ai•4mo ago

<@1000169766939529309> Kapa.ai is still learning and improving, please let me know how I did by reacting below.

DawitOP•4mo ago

@kapa.ai How can i do that in a type-safe way

kapa.ai•4mo ago

Let me check the knowledge base for you again. One moment! :books:

Solution

kapa.ai•4mo ago

---------------------- To expose module options to runtime in a type-safe way in Nuxt 3, you should: 1. Define a Type for Your Module Options:
Create a TypeScript interface for your module options. 2. Use That Type in Your Module:
Pass your type to defineNuxtModule<YourOptionsType>() so that options are type-checked in the module setup. 3. Augment the RuntimeConfig Type:
Extend the PublicRuntimeConfig (or RuntimeConfig for server-only) interface in a index.d.ts file to include your module's options. This ensures that when you access useRuntimeConfig().public.myModule, TypeScript knows the shape of your options. Example:

// types/my-module.d.ts
export interface MyModuleOptions {
  foo: string
  bar?: number
}

// types/my-module.d.ts
export interface MyModuleOptions {
  foo: string
  bar?: number
}

// nuxt.config.ts
import type { MyModuleOptions } from './types/my-module'

export default defineNuxtConfig({
  modules: [
    // your module
  ],
  myModule: {
    foo: 'hello',
    bar: 42
  } as MyModuleOptions,
  runtimeConfig: {
    public: {
      myModule: {} as MyModuleOptions
    }
  }
})

// nuxt.config.ts
import type { MyModuleOptions } from './types/my-module'

export default defineNuxtConfig({
  modules: [
    // your module
  ],
  myModule: {
    foo: 'hello',
    bar: 42
  } as MyModuleOptions,
  runtimeConfig: {
    public: {
      myModule: {} as MyModuleOptions
    }
  }
})

// my-module.ts
import { defineNuxtModule } from '@nuxt/kit'
import type { MyModuleOptions } from './types/my-module'
import { defu } from 'defu'

export default defineNuxtModule<MyModuleOptions>({
  meta: { name: 'my-module' },
  defaults: {
    foo: 'default'
  },
  setup(options, nuxt) {
    nuxt.options.runtimeConfig.public.myModule = defu(
      nuxt.options.runtimeConfig.public.myModule,
      options
    )
  }
})

// my-module.ts
import { defineNuxtModule } from '@nuxt/kit'
import type { MyModuleOptions } from './types/my-module'
import { defu } from 'defu'

export default defineNuxtModule<MyModuleOptions>({
  meta: { name: 'my-module' },
  defaults: {
    foo: 'default'
  },
  setup(options, nuxt) {
    nuxt.options.runtimeConfig.public.myModule = defu(
      nuxt.options.runtimeConfig.public.myModule,
      options
    )
  }
})

// index.d.ts (in your project root)
import type { MyModuleOptions } from './types/my-module'

declare module 'nuxt/schema' {
  interface PublicRuntimeConfig {
    myModule: MyModuleOptions
  }
}
export {}

// index.d.ts (in your project root)
import type { MyModuleOptions } from './types/my-module'

declare module 'nuxt/schema' {
  interface PublicRuntimeConfig {
    myModule: MyModuleOptions
  }
}
export {}

Now, when you use:

const options = useRuntimeConfig().public.myModule

const options = useRuntimeConfig().public.myModule

kapa.ai•4mo ago

TypeScript will provide full type safety and autocompletion for your module options. Note:
This approach is based on the official Nuxt documentation for altering Nuxt configuration and exposing options to runtime, and for typing runtime config. The knowledge sources do not mention the new .with() API for type inference, so the above is the most type-safe approach documented. ---------------------- Note: you can ask me a follow up question by @ mentioning me again :speech_balloon: ----------------------

kapa.ai•4mo ago

<@1000169766939529309> Kapa.ai is still learning and improving, please let me know how I did by reacting below.

Gaming

Programming

Passing module options to runtime

Did you find this page helpful?