Better API for Auto Imports Customization

[ShayanTheNerd]

trafficstars

Describe the feature

Nuxt and its great, out-of-the-box DX are really enjoyable. However, I still prefer explicit imports over automatic ones, with exception for very well-known utilities and composables; such as the ones exposed by Vue's core.

While configuring Nuxt to disable the auto-importing of almost everything, I noticed the API isn't really intuitive and could be improved. The problem is that in addition to having set imports: { autoImport: false }, we have to explicitly disable component auto-imports using components: false or components: { dirs: [] }. Even though everything is documented well, having to separately disable component auto-imports feels like an extra, not-really-obvious step. TBH, this isn't a big deal. However, things get worse when it comes to not just disabling auto-imports, but rather customizing it.

I wanted to disable all auto-imports, and only have the presets of Vue & Vitest auto-imported. Unfortunately, the API isn't flexible enough to let me do something like this and call it a day:

imports: {
   autoImport: 'presets', // Boolean | 'presets'
   presets: ['vitest', /* Vue's preset seems to be included by default. */],
},

So, I came up with this solution by playing around with different imports hooks:

// Disable auto-importing custom components, composables, and utilities.
components: {
   dirs: [],
},
imports: {
   presets: ['vitest'],
},
hooks: {
   'imports:extend': (imports) => {
      imports.length = 0;
   },
}, 

I'd really appreciate it if the team considers a more flexible and intuitive API.

Additional information

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

Final checks

• [x] Read the contribution guide.
• [x] Check existing discussions and issues.

[tobychidi]

Also I'd like to bring this to attention on the topic of imports. When in Nuxt 4 compat mode custom imports don't work as before?

i.e.

imports: {
   dirs: ["globals"],
}

But Nitro imports still work. I had to use resolve, node:path to fix it. I reckon it could be due to the new directory structure. I didn't come accross any documentation for it as well.

[danielroe]

@tobychidi it seems to work fine for me.

imports.dirs is resolved relative to your srcDir (which is app/). You can also pass an aliased path like ~/globals.

[danielroe]

@ShayanTheNerd Do you have any suggestions for a good API?

[ShayanTheNerd]

@ShayanTheNerd Do you have any suggestions for a good API?

The configuration of component auto-imports should become part of the imports config key. Old:

imports: {
  presets: ["pinia"],
},
components: {
  dirs: ["~/components"],
},

New:

imports: {
  presets: ['pinia'],
  components: {
    dirs: ["~/components"],
  },
},

Also, we should be able to disable auto-imports of every sort (including Vue and Nuxt built-ins) with a single boolean. Old:

imports: {
  scan: false,
  autoImports: false, // AFAIU, this is supposed to disable Vue and Nuxt built-ins, but it doesn't work for me.
},
components: false,

New:

imports: false,

/* Or if you want Vue and Nuxt built-ins: */
imports: {
  autoImport: 'presets', // The type `Boolean`, or even the whole key, is probably not necessary anymore.
  presets: ['vue', 'nuxt'], // vue and nuxt could be the default presets.
}

In the end, to be even more explicit, the config key imports could be renamed to autoImports.

[Hebilicious]

Pasting an excerpt from my comment about the now duplicated issue https://github.com/nuxt/nuxt/issues/29923#issuecomment-2529500400 as it seems relevant :

---

It would also want to see a consolidation of all the auto import settings underneath a single key, to make it easier to enable, disable, understand and share import settings between project. Maybe we can provide a few presets out of the box, nuxt3 or minimal for the people who like them.

Something like this :

import { autoImports } from "nuxt"
const legacy = defineNuxtConfig({ autoImports: autoImports("nuxt3") }) // Some preset
const noImport = defineNuxtConfig({ autoImports: false }) //Disable everything

It should be straightforward to get the same configuration as now and to disable everything, with a sensible default to make sure that nothing breaks. The new settings key would be used to configure auto-imports for everything, unimport presets, components, composables, modules, nitro, custom directories etc

For modules specifically, I would love to be able to enable or disable auto-imports for a given module, without needing to touch the module configuration itself : For example in this module there's a setting to disable them, but I should be able to override auto-import for any module like this :

export default defineNuxtConfig({ autoImports: { modules: { myModule: false } } })

---

I'm in favour of using a single key so that we can import full presets and re-use them easily accross projects. Presets must be fully serializable, and must contain everything related to auto-imports.

For example we should find the following keys underneath autoImport :

• uninmportPresets
• components
• modules
• composables
• nitro
• customDirs