Fix: Invalid Plugin src Option Required in Nuxt

What Causes This Error?

This error occurs when you try to register a plugin in nuxt.config.ts or via @nuxt/kit without providing the required src path to the plugin file.

The Problem

// nuxt.config.ts
export default defineNuxtConfig({
  plugins: [
    // ❌ Wrong - missing src
    { mode: 'client' },

    // ❌ Wrong - empty object
    {}
  ]
})

// modules/my-module.ts
import { addPlugin } from '@nuxt/kit'

export default defineNuxtModule({
  setup() {
    // ❌ Wrong - no src provided
    addPlugin({
      mode: 'client'
    })
  }
})

The Fix

Provide the src Path

// nuxt.config.ts
export default defineNuxtConfig({
  plugins: [
    // ✅ Correct - string path
    '~/plugins/my-plugin.ts',

    // ✅ Correct - object with src
    { src: '~/plugins/client-only.ts', mode: 'client' },

    // ✅ Correct - object with src
    { src: '~/plugins/server-only.ts', mode: 'server' }
  ]
})

In Module Development

// modules/my-module.ts
import { addPlugin, createResolver } from '@nuxt/kit'

export default defineNuxtModule({
  setup() {
    const resolver = createResolver(import.meta.url)

    // ✅ Correct - provide src
    addPlugin({
      src: resolver.resolve('./runtime/plugin.ts')
    })

    // ✅ With mode
    addPlugin({
      src: resolver.resolve('./runtime/client-plugin.ts'),
      mode: 'client'
    })
  }
})

Plugin Registration Methods

Simple String Path

// nuxt.config.ts
export default defineNuxtConfig({
  plugins: [
    '~/plugins/analytics.ts',
    '~/plugins/api.ts'
  ]
})

Object Format

// nuxt.config.ts
export default defineNuxtConfig({
  plugins: [
    { src: '~/plugins/analytics.ts' },
    { src: '~/plugins/client.ts', mode: 'client' },
    { src: '~/plugins/server.ts', mode: 'server' }
  ]
})

File Convention (Auto-registered)

plugins/
├── analytics.ts         # Both client and server
├── tracking.client.ts   # Client only (auto)
└── logging.server.ts    # Server only (auto)

Module Plugin Registration

// modules/my-module/index.ts
import { defineNuxtModule, addPlugin, createResolver } from '@nuxt/kit'

export default defineNuxtModule({
  meta: {
    name: 'my-module'
  },
  setup(options, nuxt) {
    const resolver = createResolver(import.meta.url)

    // ✅ Standard plugin
    addPlugin({
      src: resolver.resolve('./runtime/plugin')
    })

    // ✅ Client-only plugin
    addPlugin({
      src: resolver.resolve('./runtime/client'),
      mode: 'client'
    })

    // ✅ Server-only plugin
    addPlugin({
      src: resolver.resolve('./runtime/server'),
      mode: 'server'
    })
  }
})

Plugin file:

// modules/my-module/runtime/plugin.ts
export default defineNuxtPlugin(() => {
  console.log('Module plugin loaded!')
})

Conditional Plugins

// nuxt.config.ts
export default defineNuxtConfig({
  plugins: [
    // Always include
    '~/plugins/core.ts',

    // Conditional based on environment
    ...(process.env.NODE_ENV === 'production'
      ? ['~/plugins/production.ts']
      : []),

    // Conditional based on config
    ...(process.env.ENABLE_ANALYTICS === 'true'
      ? [{ src: '~/plugins/analytics.ts', mode: 'client' }]
      : [])
  ]
})

Plugin Options Object

// Full options available
{
  src: '~/plugins/my-plugin.ts',  // Required: path to plugin
  mode: 'all',                    // Optional: 'all' | 'client' | 'server'
  order: 0                        // Optional: execution order (lower = earlier)
}

Common Mistakes

Missing File

// ❌ File doesn't exist
plugins: ['~/plugins/nonexistent.ts']

// ✅ Verify file exists
plugins: ['~/plugins/existing.ts']

Wrong Path

// ❌ Wrong path format
plugins: ['plugins/my-plugin.ts']

// ✅ Use ~/ for project root
plugins: ['~/plugins/my-plugin.ts']

Module Path Issues

// modules/my-module/index.ts
export default defineNuxtModule({
  setup() {
    // ❌ Wrong - relative path won't work
    addPlugin({ src: './runtime/plugin.ts' })

    // ✅ Use resolver
    const resolver = createResolver(import.meta.url)
    addPlugin({ src: resolver.resolve('./runtime/plugin') })
  }
})

Debugging

// nuxt.config.ts
export default defineNuxtConfig({
  hooks: {
    'app:resolve'(app) {
      console.log('Registered plugins:', app.plugins.map(p => ({
        src: p.src,
        mode: p.mode
      })))
    }
  }
})

Quick Checklist

• Every plugin entry has a src path
• Path starts with ~/ for project files
• File exists at the specified path
• Use createResolver in modules
• Mode is optional (‘all’ by default)
• Check for typos in path