Custom config schema

[pi0]

In Nuxt 3, we have introduced a new package @nuxt/schema that holds types, defaults, and documentation for all build-in configurations for Nuxt and from one source using untyped. In comparation with Nuxt 2, these were separately maintained, often with inconsistencies. This new system is also designed to be future proof to be able to manage configuration via UI using generated (JSON)Schema files and also runtime validation to notice any usage issues.

For Nuxt modules, it is already possible to extend a typescript interface ModuleOptions to provide types, however it has same limitations of Nuxt 2 era. We have introduced new schema in new @nuxt/kit module definition system however it became unused.

With the introduction of Nuxt Layers, themes can also now require some specific configuration. Most importantly for configuring runtimeConfig and app config (either via appConfig or app.config)

For this, we can use the same tooling (untyped) as a built-in feature to allow providing custom configuration schemas from Nuxt layers and modules (also directly from a Nuxt project). Benefiting from most possibilities (note 1) we have already for core config.

We have made an experiment nuxt-experiments/nuxt-config-schema that is now almost ready to be moved into a core experiment, allowing to make it better usable. It is possible to provide custom config schema for nuxt projects in different ways:

• Using nuxt.schema.ts in main Nuxt project or a layer
• Using $schema key in nuxt.config
• Extend nuxt.options.$schema for modules
• Extend schema using schema:extend, schema:resolved and schema:beforeWrite for modules (note 2)
• Use schema in defineNuxtModule (recommended way for modules. also supports defaults)

The output will be in .nuxt directory and initially mainly usable for the Augmentation of types and custom purposes such as UI.

Notes:

note 1: Since development and trial of the experimental module, one particularly important point we found is that, unlike the core usage, mixing schema with defaults is not a good practice. We can only merge schema after modules are setup and it is too late for them to reapply new defaults and do their config handling logic and also it makes it much harder to merge runtime configuration such as app.config since custom merger logic resides in runtime while schema is in the build-time namespace and merging strategy is different.

note 2: We have introduced two separate hooks. extend/resolve as main way to extend schema just after all modules are initialized and before core or any other place tries to use schema and another beforeWrite as last resort (less recommended) for when a module needs to extend schema based on build aftertifacts coming from webpack, rollup or nitro's rollup step and it mainly and only affects the written files.

[Baroshem]

I am not sure about this feature. I mean, I understand the reasoning behind it, just not sure if it will deliver value to the users.

I cant find a really good example of the usage of this feature. For me, it's a bit like a nice to have feature that I will probably never use because I will keep using the default config schema.

But this is just my opinion :)

[pi0]

Main benefit is mostly for module and theme authors to extend schema. End users will have better types in first version (later bringing devtools ui)

[xxwangkaimin]

Why did I report a TS error when configuring buildDir Argument of type '{ buildDir: string }' is not assignable to parameter of type 'NuxtConfig'.   Object literal may only specify known properties, and 'buildDir' does not exist in type 'NuxtConfig'.: