Interoperability between Nitro modules and Vite plugins

[pi0]

Note

A POC version landed via #3712

Nitro (similar to Nuxt) has a concept of "Modules" which are basically build time plugins that can hook into the nitro builder instance, to modify config, add integrations, add routes, hook into build lifecycle, etc.

The format of modules is either a function or an { name, setup } object:

export default (nitro: Nitro) => { /* ... */ }

export default {
  name: "my-module",
  setup(nitro: Nitro) { /* ... */ }
}

In order to register modules, they go to Nitro config:

import { defineNitroConfig } from 'nitro/config'

export default defineNitroConfig({
  moules: ["my-module"], // auto imported
  myModule: { /* config */ }
})

Or with Vite+Nitro:

import { defineConfig } from 'vite'
import { nitro } from 'nitro/vite'

export default defineConfig({
  plugins: [nitro()],
  nitro: {
    modules: ['my-module'],
    myModule: { /* config */ }
  }
})

---

In vite projects, it would feel more natural if everything is just a vite plugin. Thefore something like this:

import { defineConfig } from 'vite'
import { nitro } from 'nitro/vite'
import myModule from 'myModule'

export default defineConfig({
  plugins: [nitro(), myModule(/* config */)],
})

In order to make this working, we need to support a new interopablable module namespace format with nitro hook:

export default function myModule(options) {
   return {
      name: "my-module"
      nitro: (nitro: Nitro) => { /* ... */ }
   }
}

or

export default function myModule(options) {
   return {
      name: "my-module"
      nitro: {
		setup: (nitro: Nitro) => { /* ... */ }
      }
   }
}

Then Nitro vite plugin can try to find those from user config and apply plugins with nitro key/hook as modules to extend Nitro instance.

--

/cc @nitrojs/vite

[antfu]

I love the { nitro: { setup: () => {} } in Vite Plugin! And let it also exactly how Vite DevTools extends it ({ devtools: { setup: () => {} }), as part of the Vite+ Plugin (also a superset of Vite Plugin).

My only concern (from the Vite team perspective) is that if this would open the door for other tools to keep augmenting the Vite Plugin API (like package.json). But for the case of Nitro, IMO, it would be important enough to deserve having this field.

I referenced this discussion to the Vite/Vite+ teams to see if we can have a consensus on this.

[pi0]

Thanks for early feedback.

nitro namespace is explicit (not something generic like server) i hope it helps to avoid namespace overlaps.

[sapphi-red]

Maybe we can create a registry like https://github.com/WinterTC55/import-meta-registry ?

But I think the safer way would be to put it under the api property, which is the way Rollup recommends. (we can still have a registry for this one as well)

export default function myModule(options) {
   return {
      name: "my-module",
      api: {
        nitro: (nitro: Nitro) => { /* ... */ }
      }
   }
}

[pi0]

Namespace registry sounds a cool idea specially that it makes types much universal across rollup/rolldown/vite/vite+ compatible plugins!

Im a little bit hesitant re using api namespace since for rollup plugins, it is meant for exposing callable utils. nitro.setup is kinda a one time hook. We might later even support order for it.

(maybe we can introduce a new namespace for safety like addons/custom/extensions? but im more favor of having explicitly known top level key as it makes authoring universal nitro modules easier without wrapper)

[pi0]

Adding an initial version to try the idea via #3712, still if vite team feels to adovcate a nested namespace i appreciate it and in that case we can adopt and advocate new one 💯

[bluwy]

Im a little bit hesitant re using api namespace since for rollup plugins, it is meant for exposing callable utils. nitro.setup is kinda a one time hook.

I don't think api is strictly for that, e.g. vite-plugin-svelte used to (now removed for different reasons) support api.sveltePreprocess to allow Vite plugins to hook to and preprocess Svelte files: https://github.com/sveltejs/vite-plugin-svelte/blob/63d1fc6809c5f9e1e5ed3116d417c82d8781079d/docs/faq.md#how-do-i-add-a-svelte-preprocessor-from-a-vite-plugin

I personally don't mind not using api, but if it could use it, it may prevent diverging ecosystem patterns in the future.

[onmax]

Related: #4250

What seems missing is a path for a Nitro module to contribute a dev-only root Vite plugin, so it can register with Vite DevTools via devtools.setup(ctx)