allow disabling auto imports

[darthf1]

Describe the feature

First mentioned here by @nikolay-zoteev and @cawa-93 in https://github.com/nuxt/framework/discussions/2271.

I would like to be able to disable auto import, so I can make explicit imports from respective vendor library required in the codebase.

import { ref } from '#imports'

Would become:

import { ref } from 'vue'

Additional, from https://github.com/nuxt/framework/discussions/2271#discussioncomment-2906232:

I still need a reliable and documented way to turn off auto-import.

• Auto-import does not work for the server part
• Auto-import doesn't work for everyone. You still have business logic modules, helpers, utilities, services that you have to import on your own (actually IDE will do everything for you).
• Only top level files can be auto-imported.
• Auto-import of asynchronous components (such as those created by defineAsyncComponent) is not possible.

In addition

• Auto-import complicates IDE code analysis (jet brains have issues with deep import analysis)
• It takes twice as long to go from calling a component to declaring it

Additional information

• Would you be willing to help implement this feature?
• Could this feature be implemented as a module?

Final checks

• Read the contribution guide.
• Check existing discussions and issues.

[cawa-93]

Only top level files can be auto-imported.
Auto-import of asynchronous components (such as those created by defineAsyncComponent) is not possible.

It was solved for me

[danielroe]

This is a reasonable request, but just to address some of your comments:

Only top level files can be auto-imported.

You can configure this with autoImports.dirs

Auto-import does not work for the server part

Auto imports can be configured for nitro within nitro.autoImport

Auto-import of asynchronous components

You can use resolveComponent('SomeAsyncComponent') if they are registered or marked as global components.

[antfu]

In addition to @danielroe's note:

Only top level files can be auto-imported.

Supported since nuxt/framework#6025

[darthf1]

I got far with some local changes, but in the end got a build error related to the defineNuxtPlugin import:

tsconfig.json

{
  "$schema": "https://json.schemastore.org/tsconfig",
  "extends": "./.nuxt/tsconfig.json",
  "compilerOptions": {
    "experimentalDecorators": true,
    "paths": {
      "~/*": ["./*"],
      "@/*": ["./*"]
    }
  }
}

nuxt.config.ts

import { defineNuxtConfig } from 'nuxt'

export default defineNuxtConfig({
  hooks: {
    'autoImports:sources': (sources) => sources.splice(0, sources.length),
    'autoImports:dirs': (dirs) => dirs.splice(0, dirs.length),
    'components:dirs': (dirs) => dirs.splice(0, dirs.length),
  },
}

a-plugin.ts

import { defineNuxtPlugin } from 'nuxt'

export default defineNuxtPlugin(() => {
    ... do something
})

Error:

#0 1.344 > nuxt build
#0 1.344 
#0 1.387 Nuxt CLI v3.0.0-rc.8
#0 6.251 
#0 6.251  ERROR  [nuxt:auto-imports-transform] [unimport] failed to find "defineNuxtPlugin" imported from "#imports"
#0 6.251 file: /home/node/app/node_modules/@pinia/nuxt/dist/runtime/plugin.vue3.mjs
#0 6.251 
#0 6.251 
#0 6.251  ERROR  [unimport] failed to find "defineNuxtPlugin" imported from "#imports"
#0 6.251 
#0 6.251   at node_modules/unimport/dist/chunks/context.mjs:716:17
#0 6.251   at Array.forEach (<anonymous>)
#0 6.251   at node_modules/unimport/dist/chunks/context.mjs:713:44
#0 6.251   at Array.forEach (<anonymous>)
#0 6.251   at detectImports (node_modules/unimport/dist/chunks/context.mjs:711:20)
#0 6.251   at injectImports (node_modules/unimport/dist/chunks/context.mjs:738:50)
#0 6.251   at async Object.transform (node_modules/nuxt/dist/index.mjs:885:21)

I also noticed that /.nuxt/imports.d.ts was not empty:

export { usePinia } from '../node_modules/@pinia/nuxt/dist/runtime/composables';
export { definePageMeta } from '../node_modules/nuxt/dist/pages/runtime/composables';
export { useLink } from 'vue-router';

[darthf1]

What would be the correct import path for defineNuxtPlugin without auto import?

Using Github search, I found a few files which have an import statement:

import { defineNuxtPlugin } from '#app'

In Pinia, the following import statement is used:

import { defineNuxtPlugin } from '#imports'

It could be that in the end it boils down to the same, I dont know :)

But I could not find a .ts or .d.ts file or something similar where this function is exported, which can then be used instead of #app or #imports.

[danielroe]

Yes, we advise using #imports. This ensures it's always resolved properly. You can see the original sources of these files in .nuxt/types/auto-imports.d.ts.

[Skwai]

I really think auto-importing is a bad design feature. One of the reasons I dislike RoR. Not knowing explicitly where your code is coming from makes large projects (especially onboarding new devs into projects) extremely hard to reason about. But that's just my opinion.

[danielroe]

You should be able to see where any auto import is coming from by clicking on it in your ide. There are also tools in Nuxt devtools that will show you a bigger overview.

[Skwai]

@danielroe that's just the tip of the iceberg. I'm currently battling how to set up Vitest to work with Nuxt3 (Nuxt tests are barely mentioned, nor how to configure test frameworks to work with auto-imports).

I'm also trying to work out how to override the type definitions for a Nuxt3 plugin that's being auto imported.

The extra complexity required to get this feature to work is not nearly worth it (IMO).

[Skwai]

I also don't get why we need to alias #imports and not import out of the actual package itself (like regular Vue).

[danielroe]

You can use https://github.com/danielroe/nuxt-vitest, where these should all be set up for you.

[Skwai]

I'm using that but it doesn't cover several things eg. useRuntimeConfig which then has to be mocked right? But it's not clearly stated.

Trying to get everything working is a real dance.

[Skwai]

How it feels:

[Skwai]

Let me state that I appreciate everything you guys have created here.

But as someone who has been a long time user of Vue, there are several design decisions made in Nuxt that are relatively alien to Vue and trying to achieve simplicity (eg. auto-imports) just moves the complexity elsewhere.

If someone is using Nuxt they probably also know how to use Vue (which doesn't have auto-importing) so I'm not sure who we're trying to protect with this feature.

[cawa-93]

Nuxt's imports design is just abyss of problems. Especially refactoring. You know, move files, rename them, group things. Casual things, but in Nuxt it's incredible pinhead pleasure. 🤌🤌🤌
That was more than a year ago when I wrote in the original discussion. Since then, not much has changed. I have written so many threads and articles criticizing implicit imports.

[cawa-93]

My favorite is naming collision 🤤. This is such an apt retrospect of the 00 years, when all variables were global, and one module in some file affected the work of another. Nice 🙃
https://twitter.com/alex_kozack/status/1659141957275340800

[basemkhirat]

With big projects. Auto import works like a hell. It should be turned of by default.

[ByScripts]

I really don't like the auto import feature either.

It should be an opt-in, not an opt-out.

At least we should be able to disable it completely, easily.

BTW, is there a way to disable the generation of imports.d.ts? I don't want to import from #imports

I added this in nuxt.config.ts, but it's not sufficient:

  components: false,
  imports: {
    autoImport: false,
  },

[drewsher]

I was able to partially disable auto-import. in my case, it was necessary to exclude utils from the general list of auto-imports. To do this, you need to use the imports:dirs hook to remove the element, but not return anything:

export default defineNuxtConfig({
  hooks: {
    'imports:dirs'(dirs) {
       const rules = ['utils'];

       for (const rule of rules) {
         const index = dirs.findIndex((dir) => dir.includes(rule));

         dirs.splice(index, 1);
       }
    }
  }
})