DX for what can be imported in nitro vs vue context

[danielroe]

In a Nuxt app, there are two different contexts:

1. The Nitro context, in which event handlers run.
2. The Vue context (client and server) in which Nuxt plugins, route middleware, components, pages, etc. run

What is available in these two different contexts is dramatically different, although in some cases utilities can be imported in both places, or shared between them:

1. Same utility. In some cases the same utility can be used in each context. We are currently discussing whether to support h3's createError in the Vue portion of the app in feat(nuxt): improve error dx for users framework#4539, for example.
2. Different utilities with same name and signature. useRuntimeConfig() has a same name and DX but is a different utility in Nitro and Vue.
3. Utilities that are only available in one context. For example, defineEventHandler or defineComponent.
4. Different utilities with same name but different signature. For example, useCookie.

For 1 and 2, we don't have an issue. But for 3 and 4, we have the problem that users may use the 'wrong' import, either because it isn't provided via auto-imports in the context in which they are using it, or because it won't work in that context. Even worse, they may import directly from #app in a server context, or try to import from nitro in a Vue context.

There are a number of potential ways to resolve this and this issue exists for discussion of these and other potential solutions. They are not mutually exclusive.

1. Provide clearer hints in the naming of composables (e.g. defineServerCookie).
2. Ensure there is either a common signatures or different names for functions.
3. Provide runtime checks (which we currently do through import protection).
4. Provide separate TypeScript environments so IDEs can recognise differences.

Other ideas are welcome!

Related: #13713

cc: @pi0, @Atinux, @antfu

[pi0]

Thanks for the summary @danielroe 💚

I think case for (1), is the most urgent to resolve by adding server prefix for alias (here) (solution 1) and in the longer term we can introduce them back with same signature (2) using implicit context via unctx in server routes.

Regarding environment safely, I belive we need to somehow merge two instances of unimport (nuxt and nitro) to be aware of each other and generate proper error or a mock that throws error when using auto imports with the wrong file context (/cc @antfu can we please have an issue for this)

Having greater typescript safely for filtering #imports is also a nice idea but runtime+buildtime safetely is probably much more important to have at first. Consider we need to properly try IDE integration and also update module-builder to adhere same convention for hinting types from src/runtime/server.

[danielroe]

I think we can try two possible solutions here:

1. a ~/server/tsconfig.json that extends a server-specific tsconfig which is able to split out server auto-imports
2. generate typescript modules within .nuxt that apply to server files specifically to modify the global scope