nuxt-configs

Automatically load configs for nuxt and nitro runtimes from the ~/configs directory. This may be useful for nuxt module configs requiring non-serialzable values. If you are not a module author, you can still use this module to provide common configurations for your Nuxt and Nitro.

Features

• 🌲 Provide a common configuration interface (~/configs) that allows various Nuxt modules to access and be used in both Nuxt and Nitro runtimes.

• nuxt-configs

  • Features
  • Usage (common)
    • app.ts
    • nitro.ts
  • Usage (Nuxt module)
  • Layer
  • Why?
  • License

Usage (common)

Install the module to your Nuxt application.

npm install -D @crazydos/nuxt-configs

export default defineNuxtConfig({
  modules: ['@crazydos/nuxt-configs'],
})

After setting it up, you can configure app.ts (for the Nuxt environment) and nitro.ts (for the Nitro environment) in the <rootDir>/configs directory.

|--<rootDir>
|--/configs <-- (here)
|----app.ts <---- (for the Nuxt environment)
|----nitro.ts <-- (for the Nuxt environment)
|--app.vue
|--/pages

app.ts

The configuration in app.ts can be accessed within the Nuxt runtime, including .vue files, plugins, and other related files. The configuration is set up as follows:

// configs/app.ts
import { defineNuxtAppConfig } from '#configs'

export default defineNuxtAppConfig({
  foo: {
    name: "foo",
    bar: () => {}
  }
})

<!-- app.vue -->
<script setup lang="ts">
const configs = useNuxtAppConfig()

configs.foo.name
configs.foo.bar()
</script>

You can define the type for the config using the following approach. First, create a .d.ts file in the rootDir, then:

// <rootDir>/global.d.ts
declare module '#build/client.config.mjs' {
  export const configs: {
    // e.g: 
    foo: {
      name: string,
      bar: CallableFunction
    }
  }
}

[!WARNING] Configuration in app.ts may be exposed in browser, DON't put any secret, credentials in it.

nitro.ts

The configuration in nitro.ts can be accessed within the Nitro runtime, including files under server/api and server/plugins, etc. The configuration is set up as follows:

// configs/nitro.ts
import { defineNuxtNitroConfig } from '#configs'

export default defineNuxtNitroConfig({
  foo: {
    name: "foo",
    bar: () => {}
  }
})

export default defineNitroPlugin(() => {
  const config = useNuxtNitroConfig()
  config.foo.bar()
})

You can define the type for the config using the following approach. First, create a .d.ts file in the rootDir, then:

// <rootDir>/global.d.ts
declare module '#configs/nitro' {
  export const configs: {
    // e.g: 
    foo: {
      name: string,
      bar: CallableFunction
    }
  }
}

Usage (Nuxt module)

If you are using this module in your own Nuxt project, you can refer to the Usage (common) section above. If you are a module package author, you can use the interface provided by this module as follows:

First, you need to add @crazydos/nuxt-configs as a dependency and install this module within your own Nuxt module.

npm install @crazydos/nuxt-configs

import { installModule } from '@nuxt/kit'
export default defineNuxtModule<ModuleOptions>({
  // ...
  setup(_options, _nuxt) {
    installModule('@crazydos/nuxt-configs')
  }
})

Next, you can define the type for your module’s configuration by .d.ts.

// src/runtime/config.nitro.d.ts
declare module '#configs/nitro' {
  /** define myModule nitro options */
  const myModule: Record<string, unknown>
}

// src/runtime/config.nuxt.d.ts
declare module '#build/client.config.mjs' {
  /** define myModule client options */
  const myModule: Record<string, unknown>
}

[!NOTE] Put these .d.ts in runtime directory.

Last, add these type files by helpers export from @crazydos/nuxt-configs/utils.

import { installModule } from '@nuxt/kit'
export default defineNuxtModule<ModuleOptions>({
  // ...
  setup(_options, _nuxt) {
    installModule('@crazydos/nuxt-configs')

    // Add .d.ts to buildDir or it will lost.
    const resolver = createResolver(import.meta.url)
    addAppConfigTypeFile(_nuxt, 'myModule', resolver.resolve('./runtime/config.nuxt.d.ts'))
    addNitroConfigTypeFile(_nuxt, 'myModule', resolver.resolve('./runtime/config.nitro.d.ts'))
  }
})

Finally, you can instruct your users to place your module’s configuration in <rootDir>/configs/app.ts and <rootDir>/configs/nitro.ts. You can then use these configurations within your module's runtime code.

// src/runtime/server/plugins.ts
export default defineNitroPlugin(() => {
  const configs = useNuxtNitroConfig()
  console.log('nitro config:', configs.myModule)
})

Layer

[!WARNING] Currently, layers are not supported.

Why?

When developing a Nuxt module, user configurations can be received through nuxt.config.ts. However, since nuxt.config.ts exists in the build environment and is separate from the Nitro and Nuxt runtimes, these configurations cannot be used directly at runtime. Instead, they need to be passed to the runtime through certain mechanisms, such as runtimeConfig or methods like addTemplate.

The simplest approach is runtimeConfig, but it can only pass serializable configurations and cannot handle functions or other non-serializable values.

// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['some-module'],
  someModule: {
    foo: "bar",
    func: () => {} // this cannot easily pass to runtime environment
  }
})

export default defineNuxtModule<ModuleOptions>({
  // ...
  setup(_options, _nuxt) {
    _nuxt.options.runtimeConfig.myModule.foo = _options.foo
  }
})

On the other hand, the addTemplate method is not very straightforward and has a certain learning curve.

This module provides a simple way for module developers to easily receive configurations and seamlessly apply them in both Nitro and Nuxt runtimes, avoiding the issues mentioned above.

// configs/nitro.ts
import { defineNuxtNitroConfig } from '#configs'

export default defineNuxtNitroConfig({
  foo: {
    name: "foo",
    bar: () => {}
  }
})

In reality, it seems that only the Nitro environment lacks such an interface (?), since Nuxt already provides app.config.ts. A better solution might be for Nuxt to introduce nitro.config.ts, which would eliminate the need for this module altogether.

License

MIT