Auto generated module option types

[Barbapapazes]

Describe the feature

This is an open discussion to track the module system's progress and centralize information.

Hello,

The current implementation of the module system is somewhat limited.

I propose a change (#2686) to make the module system more similar to Nuxt's, with auto-generated types based on the module options.

interface ModuleOptions {
  bar: string;
  foo: {
    baz: string;
  };
}

export default defineNitroModule<ModuleOptions>({
  name: "playground",
  configKey: "playground",
  setup: (nitro, moduleOptions) => {},
});

This will generate type augmentation for NitroConfig, enabling autocompletion in nitro.config.ts:

import { defineNitroConfig } from "nitropack/config";

export default defineNitroConfig({
  playground: {
    bar: "bar",
    foo: {
      baz: "baz",
    },
  },
});

In the previous snippet, an error will occur because foo must be an object.

However, the module system could also be reworked to resemble a Vite plugin (#2686 (comment)).

interface ModuleOptions {
  bar: string;
  foo: {
    baz: string;
  };
}

export default function moduleIndex(moduleOptions: ModuleOptions) {
  return {
    name: "playground",
    setup: (nitro) => {
      console.log("Hello from playground/modules/index.ts");

      const options = {
        ...{
          foo: "baz",
        },
        ...moduleOptions,
      } satisfies ModuleOptions;
    },
  };
}

And here's the corresponding nitro.config.ts:

import { defineNitroConfig } from "nitropack/config";
import moduleIndex from "./modules/index";

export default defineNitroConfig({
  modules: [
    moduleIndex({
      bar: "bar",
      foo: {
        baz: "baz",
      },
    }),
  ],
});

Additional information

• Would you be willing to help implement this feature?

[pi0]

I appreciate the time you took to write a better description.

First, I have to emphasize that Nuxt and Nitro are two completely separate projects with different design and goals. If you see a concept with similar name, it is not necessarily same.

Regarding auto-generated types, I have mentioned earlier too that I'm not sure if it is the best idea but let me clarify more.

(...in the nuxt world...)

We introduced the the magical modules concept to Nuxt long ago when we didn't support either ESM, or Typescript and we were were free to do things such as requiring literally any dependency (like modules) from Nuxt core and not caring about config type checks. We also called this feature "modules" because "plugins" concept was already used for runtime addons.

This became harder with ESM and PNPM (non hoisted deps). Projects like jiti made more workarounds to allow using same magic as before for them but it became harder (and less standard).

Nuxt 3, became typescript-first and we naturally extended the "magic" to types as well. We had to introce Nuxt kit and (yet again) the concept of "module builder" which was a discontinued project for Nuxt 1 in order to allow developing type safe module packages.

Depending on auto-generated types, more specifically for config is honestly really strange because you need the config in first place to generate/stub those types. If we want to strictly make sure config is valid, why in first place we run all nuxt modules in stub mode with unchecked types?

Nuxt does a lot of magic today. I would think twice before introducing some magical patterns if could time travel but well that's not invented yet and besides thousands of developers are happy with such magical DX today and we still managed to use workarounds to keep them possible. (while there are of course trade-offs as well. requirement of nuxt module builder and nuxi stub are two examples that magic has a cost.)

(...in the nitro world...)

Timeline-wise, i made Nitro project when we were building Nuxt 3. The "seamless" experience required some magic from Nitro most importantly generating typed fetch so it went into the initial release. But even today for generated fetch types we have lots of troubles and rethinking it.

We haven't introded modules concept until v2.8 (via #1789) and even for the initial feature, i have made sure to not do over magic about it.

Nitro is different in a way that first and most importantly, it has it's own evolution decisions for features like modules and also it is both a standalone and also composable framework to be used within higher order frameworks.

Being used standalone, i find it pretty standard practice to ask users directly import modules within their config without passing magical strings. vite, rollup and dozens more do it today.

Using in higher order, it should be completely up the the framework authors how much magic vs explicitly balance they want to give to their users. Nuxt (modules) is magical and uses auto generated types, nitro doensn't limits it. Other frameworks (such as Solid) might prefer explicitly over and Nitro doesn't limits it either by forcing it.

(...and nitro modules are good even today...)

I know i know coming from context of Nuxt only it reads strange (i bet for a Vite user is not).

import { defineNitroConfig } from "nitro/config";
import myModule from 'my-module'

export default defineNitroConfig({
  modules: [
    myModule({ /* fully type checked config */ })
  ]
}

it is possible today and keeps modules to be free whatever internal conventions they want to do.

[Barbapapazes]

Nuxt does a lot of magic today.

To be totally honest, sometimes, I really think it's too much and a simpler model like the Vite plugin could be easier for everyone.

Using in higher order, it should be completely up the the framework authors how much magic vs explicitly balance they want to give to their users. Nuxt (modules) is magical and uses auto generated types, nitro doensn't limits it. Other frameworks (such as Solid) might prefer explicitly over and Nitro doesn't limits it either by forcing it.

Never think about this but you're totally right!

Thanks a looooooooot for the clarification and the last part about 'nitro modules are good even today'. I will continue to give it a try with that in mind.

[Barbapapazes]

And if the this the way to go, shouldn't the auto module registration (in case of a local module) be removed?

import myModule from "./src/modules/myModule";

export default defineNitroConfig({
  modules: [
    myModule({
      enabled: false,
    }),
  ],

  srcDir: "src",

  compatibilityDate: "2024-08-22",
});

The myModule will be registered twice.

[pi0]

read my mind 😅 #2691