Composable auto-import circular dependency warning

[graceful sun]

Hi @broken tundra. I'm kapa.ai, your friendly support bot. I will try to answer your question by searching through the knowledge base. :wave:

---

You're correct that the Nuxt documentation recommends re-exporting nested composables via an index.ts file in the root of the composables/ directory to enable auto-imports for those nested files. This is a common pattern to work around Nuxt's default behavior of only scanning the top level of the composables/ directory for auto-imports. The docs provide this example:

// composables/index.ts
export { utils } from './nested/utils.ts'

This enables auto-import for the nested composable by re-exporting it at the top level, as Nuxt will scan index.ts for exports to auto-import Nuxt composables directory docs.

However, as you've observed, this approach can lead to circular dependency warnings if two composables import each other (directly or indirectly) via the index file, especially when Rollup (the bundler) splits them into different chunks. The warning you see is a result of this scenario, and it can indeed cause issues with execution order.

Should you manually import instead?
Yes, if you encounter circular dependency issues, it's safer to import the composable directly from its file rather than through the index. For example:

import { useRetailer } from '../useRetailer/useRetailer'

This avoids the circular reference through the index file and is recommended by the warning itself.

Why does the documentation recommend re-exporting?
The documentation suggests re-exporting for convenience and to enable auto-imports for nested composables, but it does not address the potential for circular dependencies that can arise in more complex setups. The docs do mention that you can configure Nuxt to scan nested directories directly, which can help avoid the need for re-exporting and thus reduce the risk of circular dependencies:

export default defineNuxtConfig({
  imports: {
    dirs: [
      '~/composables',
      '~/composables/**'
    ]
  }
})

This way, Nuxt will auto-import all composables in nested directories, and you won't need to re-export them in index.ts Nuxt composables directory docs.

Summary:

• Re-exporting via index.ts is a convenience, but can cause circular dependencies.
• If you hit circular dependency warnings, prefer direct imports.
• Alternatively, configure Nuxt to scan nested composables to avoid the need for re-exports.

The documentation does not explicitly warn about this circular dependency pitfall, so your caution is justified. Adjust your import strategy based on your project's complexity and dependency graph.

Nuxt composables directory docs

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon: