Depend less on auto imports

[pi0]

The history of auto import idea probably backs to Nuxt Components (an amazing initiative by @kevinmarrec) and then same time as Nuxt 3 development, thanks to @antfu, we adopted unimport.

Auto imports make the DX of writing any javascript code much more minimalistic by automatically injecting necessary import statements in the modules that need them which means full tree-shaking same as manually importing them.

However, over time, it also showed negative effects;

• When reading sources or docs it is less understandable without knowing the sources of all auto imports
• IDE support is still not perfect, we need a prepare step to generate the types, and even after that, click to jump does not always go to the source, it goes to the intermediate file,
• Some users/frameworks prefer explicitly over magical conventions.
• To save process cost, we skip auto imports for node_modules, and it implies module authors take additional care of explicitly importing from #imports virtual module.

I still love auto imports and like the ability to have them but also think we could depend less on them and keep it for advanced usage and users who already know what they are doing.

For Nitro 2.x auto import feature shall remain enabled an I think for the sake of backward compatibility, in Nitro 3.x, we might keep having #imports but deprecated. We might also think about making the auto import experience opt-in for direct nitro users. (subject to discussion, only an idea for now)

### Tasks
- [ ] Use explicit imports from their sources in docs (explicit `h3` imports)
- [ ] Update starter template to explicitly import from `nitropack/config`
- [ ] Find a more explicit alternative to `#imports` like `nitro/app` for longer term
- [ ] Investigate solution for pnpm dependency hoisting issues (one solution might be directly adding h3 as dep in starter)

[MickL]

I wrote it already in some Nuxt issues but I would love auto imports being fully disabled by default + all the docs updated for the reasons you stated. Personally I see no benefits of having auto imports, but a lots of downsides.

Right now it is not clear to developers what actually comes from H3, what from Nitro, what from Nuxt and what from Vue.

I failed multiple times disabling auto imports within a Nuxt app as well as in a Nitro app: https://github.com/unjs/nitro/issues/2305

[pi0]

Thanks for your feedback @MickL. This decision for Nuxt should happen within a Nuxt-related discussion. We might consider disabling it by default for Nitro core but probably in 1-2 more next major versions progressively.

[MickL]

Hoping to see auto imports disabled in v3 :)

[bernhardberger]

This is gonna be fun down the line refactoring tons of projects and modules. ☠️

[DesignByOnyx]

I want to throw my +1 and 2¢ on this and provide some more reasons why auto-imports cause more harm than good.

• You lose determinism because you no longer have control over how and when certain utilities are imported. Ex. a new release of rollup could break your production builds because they changed the order of something.
• The only "benefit" to auto-imports is saving a couple keystrokes. Any editor these days can write the import statements for you - you just start typing and the editor/IDE does the rest.
• Anything "magical" like this has a tendency to break or fall apart in certain unforeseen contexts. Whenever you hit one of these problems, it's nearly impossible to solve in user land - you're at the mercy of library authors to fix it or provide guidance.
• You create a bunch of non-standard names in the global namespace... which we long-ago determined was objectively bad, and most popular libraries stopped doing it by the late aughts.
• It creates all sorts of issues with typescript, especially in monorepos where you might have multiple versions of a single library, or two different packages using the same global variables (eg. mocha/jest).
• For people who care about where their code is coming from, you almost totally disable the ability to see where something comes from. I am constantly auditing functions, clicking through to source code, reading TS definitions, et al. I know I'm not the only one.
• There are currently multiple tickets open to fix auto-import related issues. Wouldn't it be nice if the authors of these awesome tools could focus on "real" issues instead of supporting some magical import mechanism from yesteryear.

The only convenient auto-import I've experienced is for JSX syntax - and it's because it changes the actual syntax of the code you're writing. Everything else should be explicit - it's 100% deterministic this way, and you'd immediately close a dozen or more open tickets and never have to worry about it again.

EDIT: @bernhardberger - you wouldn't need to rewrite anything - just add import statements to the tops of files. Also, the change is going to come in a major version bump, which usually requires code updates. This is about the most low risk "breaking change" they could make.

[antfu]

I think the reason why we have this discussion is that we agree that auto-import is not a silver bullet. While it provides interesting DX and possibilities like DI, it's indeed having some trade-offs. I agree that for Nitro to be more agnostic, it's better to deps less on it and be less opinionated - would be great to still be able to opt-in for some cases like Nuxt.

In terms of migration, I created an ESLint plugin that auto insert the import statements based on the unimport registry: https://github.com/antfu/eslint-plugin-unimport

I can set up an example repo when this is happening.

[pi0]

eslint plugin is so cool for an in-between solution love it!

[bernhardberger]

I don't disagree with you, but I fear a major breakage in the ecosystem if auto imports were removed.. not really the stability and predictability nuxt/nitro users look for after all the vue3/nuxt3 fiasco.

If the ecosystem were to break on a massive scale again this might very well be the final straw for a bunch of users that opted to use Nuxt in commercial projects.

We know we'd likely be out if something even remotely close to that scale happens again. We'd need at least a preparation period of minimum 1 major version of deprecation here.

I want to throw my +1 and 2¢ on this and provide some more reasons why auto-imports cause more harm than good.

• You lose determinism because you no longer have control over how and when certain utilities are imported. Ex. a new release of rollup could break your production builds because they changed the order of something.
• The only "benefit" to auto-imports is saving a couple keystrokes. Any editor these days can write the import statements for you - you just start typing and the editor/IDE does the rest.
• Anything "magical" like this has a tendency to break or fall apart in certain unforeseen contexts. Whenever you hit one of these problems, it's nearly impossible to solve in user land - you're at the mercy of library authors to fix it or provide guidance.
• You create a bunch of non-standard names in the global namespace... which we long-ago determined was objectively bad, and most popular libraries stopped doing it by the late aughts.
• It creates all sorts of issues with typescript, especially in monorepos where you might have multiple versions of a single library, or two different packages using the same global variables (eg. mocha/jest).
• For people who care about where their code is coming from, you almost totally disable the ability to see where something comes from. I am constantly auditing functions, clicking through to source code, reading TS definitions, et al. I know I'm not the only one.
• There are currently multiple tickets open to fix auto-import related issues. Wouldn't it be nice if the authors of these awesome tools could focus on "real" issues instead of supporting some magical import mechanism from yesteryear.

The only convenient auto-import I've experienced is for JSX syntax - and it's because it changes the actual syntax of the code you're writing. Everything else should be explicit - it's 100% deterministic this way, and you'd immediately close a dozen or more open tickets and never have to worry about it again.

EDIT: @bernhardberger - you wouldn't need to rewrite anything - just add import statements to the tops of files. Also, the change is going to come in a major version bump, which usually requires code updates. This is about the most low risk "breaking change" they could make.

[MickL]

Why not make auto-imports opt-out for Nuxt 4, but always set the opt-out option for new projects created with Nuxi, then disable them with Nuxt 5 but keep it opt-in?

[pi0]

So to clarify, this discussion is not to "remove" the auto imports feature of Nitro at all but to depend less on them.

• For default config in pure-nitro projects (disable by default in nitro and make it opt-in)
  • (Nuxt is a separate discussion, feel free to open one in the nuxt repo)
• To make sure all Nitro functionality works without auto-imports
• To make Nitro docs more clear and understandable with explicit imports

Auto imports are super useful for people who know the sources and prefer the minimal experience.

[bernhardberger]

So to clarify, this discussion is not to "remove" the auto imports feature of Nitro at all but to depend less on them.

• For default config in pure-nitro projects
  • (Nuxt is a separate discussion, feel free to open one in the nuxt repo)
• To make sure all Nitro functionality works without auto-imports
• To make Nitro docs more clear and understandable with explicit imports

Auto imports are super useful for people who know the sources and prefer the minimal experience.

That I can 100% agree with.

[pi0]

This proposal is to make auto-imports an opt-in feature for pure nitro (v3+) projects.

Locking the thread for now, thanks for all constructive feedbacks it certainly helped confirming the idea is into a right direction 🙏🏼