Fix: #imports Should Be Transformed in Nuxt

What Causes This Warning?

This warning appears when the #imports alias is being accessed directly instead of being transformed by Nuxt’s build plugins. This usually indicates a configuration issue or that code is running outside of Nuxt’s build pipeline.

Understanding #imports

#imports is Nuxt’s internal alias that provides access to all auto-imported composables, utilities, and components:

// This should be transformed at build time
import { ref, useRoute, useFetch } from '#imports'

// Into direct imports from their actual sources
import { ref } from 'vue'
import { useRoute } from 'vue-router'
import { useFetch } from '#app/composables/fetch'

Common Causes

1. Running Code Outside Build Pipeline

// ❌ Wrong - running directly with Node
// node my-script.js
import { useNuxtApp } from '#imports'  // Won't transform!

// ✅ Correct - use full package paths for scripts
import { useNuxtApp } from 'nuxt/app'

2. Vite Config Issues

// nuxt.config.ts
export default defineNuxtConfig({
  vite: {
    // ❌ This might break alias resolution
    resolve: {
      alias: {
        '#imports': './some-path'  // Don't override!
      }
    }
  }
})

3. External Build Tool

Using tools like tsup, esbuild, or rollup directly without Nuxt:

// ❌ Wrong - building with external tool
// tsup src/utils.ts
import { ref } from '#imports'  // Won't transform

// ✅ Correct - export for use within Nuxt context
export function useMyComposable() {
  // Will work when imported into Nuxt app
  const count = ref(0)
  return { count }
}

The Fix

Fix 1: Use Direct Imports in Non-Nuxt Code

For scripts or code that runs outside Nuxt:

// scripts/seed-database.ts
// ❌ Wrong
import { useRuntimeConfig } from '#imports'

// ✅ Correct - use actual package
import { loadNuxtConfig } from '@nuxt/kit'

async function seed() {
  const config = await loadNuxtConfig()
  console.log(config.runtimeConfig)
}

Fix 2: Check Build Configuration

Ensure you’re using Nuxt’s build system:

// nuxt.config.ts
export default defineNuxtConfig({
  // Don't override these internally used aliases
  alias: {
    // Let Nuxt manage #imports, #app, #build, etc.
  },

  vite: {
    // Be careful with resolve.alias
  }
})

Fix 3: Check for Conflicting Plugins

// nuxt.config.ts
export default defineNuxtConfig({
  vite: {
    plugins: [
      // ❌ Some plugins might interfere with alias resolution
      // Check if any plugin modifies resolve.alias
    ]
  }
})

Fix 4: Verify nuxt.d.ts Generation

The types file should exist:

# Check if types are generated
ls -la .nuxt/nuxt.d.ts

# If missing, regenerate
npx nuxi prepare

When This Happens

Testing Files

// ❌ Wrong - vitest might not transform
import { useNuxtApp } from '#imports'

// ✅ Correct - use @nuxt/test-utils
import { mockNuxtImport } from '@nuxt/test-utils/runtime'

// Or configure vitest properly
// vitest.config.ts
export default defineVitestConfig({
  test: {
    environment: 'nuxt'
  }
})

Module Development

// modules/my-module/runtime/composables.ts
// ✅ This is fine - will be consumed by Nuxt app
import { ref, computed } from '#imports'

export function useMyFeature() {
  // Works because it's used within Nuxt context
}

Standalone Scripts

// scripts/generate-sitemap.ts
// For standalone scripts, don't use #imports

// ✅ Option 1: Use @nuxt/kit
import { loadNuxt, buildNuxt } from '@nuxt/kit'

// ✅ Option 2: Run through nuxi
// npx nuxi generate-sitemap

Debugging

Check if the alias is being resolved:

// nuxt.config.ts
export default defineNuxtConfig({
  hooks: {
    'vite:extendConfig'(config) {
      console.log('Aliases:', config.resolve?.alias)
    }
  }
})

Working with #imports

In Components/Pages

<script setup>
// ✅ Auto-imports work - no import needed
const route = useRoute()
const { data } = await useFetch('/api/data')
</script>

In Composables

// composables/useMyFeature.ts
// ✅ Explicit import from #imports works
import { ref, computed, useRuntimeConfig } from '#imports'

export function useMyFeature() {
  const config = useRuntimeConfig()
  const count = ref(0)
  return { count, config }
}

In Server Routes

// server/api/data.ts
// ✅ Server auto-imports work
export default defineEventHandler((event) => {
  // defineEventHandler is auto-imported from h3
  return { data: 'works' }
})

Alternative: Explicit Imports

If you need to avoid #imports:

// Instead of:
import { ref } from '#imports'

// Use direct imports:
import { ref } from 'vue'
import { useRoute } from 'vue-router'
import { useRuntimeConfig } from 'nuxt/app'

Quick Checklist

• Code is running within Nuxt’s build pipeline
• Not using external bundlers for Nuxt code
• No conflicting alias configurations in vite/nuxt config
• nuxi prepare has been run to generate types
• Test environment is properly configured for Nuxt
• Using @nuxt/kit for standalone scripts