Fix: app Namespace Reserved for Nuxt

What Causes This Warning?

This warning appears when you try to use the app prefix in places reserved for Nuxt’s internal use, such as plugin provides or runtime config keys.

The Problem

// plugins/my-plugin.ts
export default defineNuxtPlugin(() => {
  return {
    provide: {
      // ❌ Wrong - 'app' prefix is reserved
      app: { config: {} },
      appHelper: () => {},
      appConfig: {}
    }
  }
})

// nuxt.config.ts
export default defineNuxtConfig({
  runtimeConfig: {
    public: {
      // ❌ Wrong - might conflict
      app: { setting: 'value' }
    }
  }
})

The Fix

Use Different Prefix

// plugins/my-plugin.ts
export default defineNuxtPlugin(() => {
  return {
    provide: {
      // ✅ Use your own prefix
      myApp: { config: {} },
      myHelper: () => {},
      customConfig: {}
    }
  }
})

For Runtime Config

// nuxt.config.ts
export default defineNuxtConfig({
  runtimeConfig: {
    public: {
      // ✅ Use specific names
      siteConfig: { setting: 'value' },
      myAppSettings: {}
    }
  }
})

Reserved Namespaces

In Plugins

// Reserved - don't use as provide keys:
provide: {
  app: {},      // ❌ Reserved
  nuxt: {},     // ❌ Reserved
  payload: {},  // ❌ Reserved
  config: {}    // ❌ Might conflict
}

// Safe to use:
provide: {
  myPlugin: {},   // ✅
  utils: {},      // ✅
  helpers: {},    // ✅
  services: {}    // ✅
}

In Runtime Config

// nuxt.config.ts
export default defineNuxtConfig({
  runtimeConfig: {
    // These are managed by Nuxt
    app: {},  // ❌ Don't define manually

    // Use custom keys
    apiSecret: '',  // ✅
    dbUrl: '',      // ✅

    public: {
      // Don't use reserved names
      app: {},      // ❌

      // Use custom keys
      apiBase: '',   // ✅
      siteName: ''   // ✅
    }
  }
})

Accessing Nuxt’s app

If you need to access Nuxt’s internal app:

// plugins/my-plugin.ts
export default defineNuxtPlugin((nuxtApp) => {
  // ✅ Access via nuxtApp parameter
  console.log(nuxtApp.vueApp)  // Vue app instance

  // ✅ Access hooks
  nuxtApp.hook('app:created', () => {
    console.log('App created')
  })
})

Common Patterns

Plugin with Custom Namespace

// plugins/services.ts
export default defineNuxtPlugin(() => {
  const api = {
    get: (url: string) => $fetch(url),
    post: (url: string, data: any) => $fetch(url, { method: 'POST', body: data })
  }

  return {
    provide: {
      // ✅ Clear, non-reserved name
      api,
      services: {
        auth: createAuthService(),
        storage: createStorageService()
      }
    }
  }
})

Usage:

<script setup>
const { $api, $services } = useNuxtApp()
const data = await $api.get('/api/users')
</script>

Module Namespace

// modules/my-module/runtime/plugin.ts
export default defineNuxtPlugin(() => {
  return {
    provide: {
      // ✅ Module-specific prefix
      myModule: {
        doSomething: () => {},
        config: {}
      }
    }
  }
})

Multiple Provides

// plugins/utils.ts
export default defineNuxtPlugin(() => {
  return {
    provide: {
      // ✅ Individual utilities
      formatDate: (date: Date) => date.toLocaleDateString(),
      formatCurrency: (amount: number) => `$${amount.toFixed(2)}`,

      // ✅ Grouped utilities
      utils: {
        slug: (text: string) => text.toLowerCase().replace(/\s+/g, '-'),
        truncate: (text: string, length: number) =>
          text.length > length ? text.slice(0, length) + '...' : text
      }
    }
  }
})

TypeScript Declaration

// types/plugins.d.ts
declare module '#app' {
  interface NuxtApp {
    $api: {
      get(url: string): Promise<any>
      post(url: string, data: any): Promise<any>
    }
    $utils: {
      slug(text: string): string
      truncate(text: string, length: number): string
    }
  }
}

export {}

Quick Checklist

• Don’t use app as provide key
• Don’t use nuxt, payload, config as provide keys
• Use unique, descriptive namespaces
• Prefix module provides with module name
• Access Nuxt internals via nuxtApp parameter
• Declare types for custom provides