Nuxt•4w ago

Future-proof way to disable auto-imports of ~/shared?

Hi there, I'm writing new code in Nuxt 3, and I noticed this note on https://nuxt.com/docs/guide/directory-structure/shared#auto-imports:

Auto-imports are not enabled by default in Nuxt v3 to prevent breaking changes in existing projects.To use these auto-imported utils and types, you must first set future.compatibilityVersion: 4 in your nuxt.config.ts.

Auto-imports are not enabled by default in Nuxt v3 to prevent breaking changes in existing projects.To use these auto-imported utils and types, you must first set future.compatibilityVersion: 4 in your nuxt.config.ts.

I'm writing code in ~/shared where multiple-files will export the same name, because they are alternate implementations of the same interface. I want to be explicit in my client+server code about which file is imported in all cases. I realize this will work on Nuxt 3, but I don't want to use a pattern that will apparently just break on Nuxt 4. Is there a way to mark specific files as "do not auto-import from this file"? Or a different recommended approach?

Nuxt

shared · Nuxt Directory Structure

Use the shared/ directory to share functionality between the Vue app and the Nitro server.

8 Replies

kapa.ai•4w ago

Hi @seth. I'm kapa.ai, your friendly support bot. I will try to answer your question by searching through the knowledge base. :wave: ---------------------- You're asking about a future-proof way to disable auto-imports from the ~/shared directory in Nuxt, particularly when you have multiple files exporting the same name. This is a valid concern when planning for Nuxt 4 compatibility. Disabling Auto-imports There are a few approaches you can take: 1. Disable Auto-imports Globally You can completely disable auto-imports in your Nuxt configuration:

export default defineNuxtConfig({
  imports: {
    autoImport: false
  }
})

export default defineNuxtConfig({
  imports: {
    autoImport: false
  }
})

This will disable all auto-imports, but you can still use explicit imports from #imports as needed Docs > Guide > Concepts > Auto-imports. 2. Disable Scanning Only If you want to keep framework functions auto-imported but disable auto-imports for your own code:

export default defineNuxtConfig({
  imports: {
    scan: false
  }
})

export default defineNuxtConfig({
  imports: {
    scan: false
  }
})

This keeps Vue/Nuxt functions like ref auto-imported but requires manual imports for your custom code Docs > Guide > Concepts > Auto-imports. 3. Custom Directory Structure Another approach is to place your shared utilities in a directory that's not automatically scanned. According to the documentation, only files in shared/utils/ and shared/types/ are auto-imported, and nested subdirectories are not scanned unless explicitly added Docs > Guide > Directory Structure > shared. You could organize your code like:

shared/
  implementations/  # Not auto-imported
    feature1.ts
    feature2.ts

shared/
  implementations/  # Not auto-imported
    feature1.ts
    feature2.ts

Then use explicit imports with the #shared alias:

import { featureFunction } from '#shared/implementations/feature1'

import { featureFunction } from '#shared/implementations/feature1'

Future-Proofing Considerations The shared directory is relatively new (available since Nuxt v3.14+) and its auto-import behavior is tied to the compatibility version setting. As you noted, in Nuxt 3, these auto-imports are disabled by default and only enabled when future.compatibilityVersion: 4 is set. If you're concerned about future compatibility, the safest approach is to use explicit imports with the #shared alias, which ensures consistent imports regardless of auto-import settings or Nuxt version changes. For your specific use case with multiple implementations of the same interface, using explicit imports from subdirectories that aren't auto-scanned would be the most robust approach. ---------------------- Note: you can ask me a follow up question by @ mentioning me again :speech_balloon: ----------------------

kapa.ai•4w ago

<@729194452001751090> Kapa.ai is still learning and improving, please let me know how I did by reacting below.

sethOP•4w ago

@kapa.ai you said:

You could organize your code like:

shared/
  implementations/  # Not auto-imported
    feature1.ts
    feature2.ts

You could organize your code like:

shared/
  implementations/  # Not auto-imported
    feature1.ts
    feature2.ts

Doesn't code in sub-folder not get built like normal? Wouldn't this mean those files could reference, e.g. '#shared' in their imports and stuff like that?

kapa.ai•4w ago

Let me check the knowledge base for you again. One moment! :books: ---------------------- You're asking an excellent follow-up question about how code in subfolders of the shared directory is built and what import restrictions apply. Files in subfolders of the shared directory are indeed built normally and are subject to the same restrictions as files directly in the shared directory. This means: 1. Code in shared/implementations/ would still be built and included in your application 2. These files would still be subject to the same import restrictions as other files in the shared directory According to the documentation:

Code in the shared/ directory cannot import any Vue or Nitro code.

Docs > Guide > Directory-structure > shared This restriction applies to all files within the shared directory, regardless of their subfolder location. The purpose of the shared directory is to contain code that can be used by both the Vue app and the Nitro server, so it must not depend on either environment specifically. Files in shared/implementations/ can still use the #shared alias to import other files from the shared directory. For example:

// This is valid in shared/implementations/feature1.ts
import { someUtility } from '#shared/utils/helpers'

// This is valid in shared/implementations/feature1.ts
import { someUtility } from '#shared/utils/helpers'

The main difference is that files in non-standard subfolders like shared/implementations/ won't be auto-imported in Nuxt 4, while files in shared/utils/ and shared/types/ would be (when compatibilityVersion: 4 is set). This approach gives you the best of both worlds - your code is properly built and can use shared utilities, but you maintain explicit imports in your application code, avoiding conflicts between implementations with the same export names. Does this clarify how subfolders in the shared directory work? ---------------------- Note: you can ask me a follow up question by @ mentioning me again :speech_balloon: ----------------------

kapa.ai•4w ago

<@729194452001751090> Kapa.ai is still learning and improving, please let me know how I did by reacting below.

sethOP•4w ago

@kapa.ai when I try to do import whatever from '#shared/foo.js from shared/subfolder/nested.js, I get:

Package import specifier "#shared/foo.js" is not defined in package

Package import specifier "#shared/foo.js" is not defined in package

However, if I do the same import from shared/toplevel.js, it succeeds.

kapa.ai•4w ago

Let me check the knowledge base for you again. One moment! :books: ---------------------- You've encountered an interesting issue with imports within the shared directory structure in Nuxt. This is related to how Nuxt handles aliases and imports within the shared folder. Based on the knowledge sources, there are a few key points that explain your issue: Why This Is Happening When you try to use #shared alias from within the shared directory itself, particularly from nested subfolders, you're running into import protection mechanisms that Nuxt has implemented. The issue appears to be that while files at the top level of the shared directory can reference other files using the #shared alias, this doesn't work properly from nested subfolders within shared. This is likely because the import protection system is designed to prevent circular dependencies and maintain strict separation between client and server code. Possible Solutions 1. Use relative imports instead of the alias: Instead of using #shared/foo.js, use relative paths like ../../foo.js or ../foo.js when importing from within the shared directory. 2. Move shared code to the top level: If possible, flatten your structure to avoid deep nesting within the shared directory. 3. Configure additional aliases: You might need to define custom aliases for your specific folder structure. Related Issues This appears to be related to several issues that have been reported in the Nuxt GitHub repository: - There was an issue with alias resolution in Nuxt 3.16.0 where aliases weren't being properly generated in tsconfig.server.json Github Issue #31325 - Another issue reported problems with the shared folder breaking changes Github Issue #30549 - There have been issues with import protections that required improved error logging Github Pull #28753 The shared directory is a relatively new feature in Nuxt (available since v3.14+), and there are still some edge cases being worked out, particularly around import resolution within nested structures. For your specific case, I recommend using relative imports when referencing files from within the shared directory structure, as this is the most reliable approach given the current implementation. Would you like me to provide more specific guidance on structuring your shared code to avoid these import issues? ---------------------- Note: you can ask me a follow up question by @ mentioning me again :speech_balloon: ----------------------

kapa.ai•4w ago

<@729194452001751090> Kapa.ai is still learning and improving, please let me know how I did by reacting below.

Gaming

Programming

Future-proof way to disable auto-imports of ~/shared?

Did you find this page helpful?