Nuxt Modules and Plugins — Extending Nuxt 3 Functionality

In this tutorial, you will learn about Nuxt Modules and Plugins. We cover key concepts, practical examples, and best practices to help you master this topic.

Learn Nuxt 3 modules and plugins: how to install modules, create plugins, and extend Nuxt's core functionality with third-party integrations.

In this lesson, you'll understand Nuxt's module ecosystem, how to install and configure modules, and how to create plugins for custom functionality.

What You'll Learn

How to find and install Nuxt modules, configure them in nuxt.config.ts, and create plugins for runtime code that runs before your app mounts.

Why It Matters

Modules and plugins extend Nuxt's capabilities without reinventing the wheel. The module ecosystem provides SEO, styling, CMS, and PWA features.

flowchart LR
    A[Nuxt Modules] --> B[@nuxt/content]
    A --> C[@nuxt/image]
    A --> D[@nuxtjs/tailwindcss]
    A --> E[@pinia/nuxt]
    A --> F[Custom Plugin]
    style A fill:#00dc82,color:#fff

Installing Modules

npm install @nuxt/content @nuxt/image @pinia/nuxt

// nuxt.config.ts
export default defineNuxtConfig({
  modules: [
    '@nuxt/content',
    '@nuxt/image',
    '@pinia/nuxt'
  ],
  
  // Module-specific configuration
  content: {
    highlight: {
      theme: 'github-dark'
    }
  },
  
  image: {
    format: ['webp', 'avif'],
    screens: { xs: 320, sm: 640, md: 768, lg: 1024 }
  }
});

Output: The modules are activated. @nuxt/content provides file-based CMS, @nuxt/image optimizes images, @pinia/nuxt adds Pinia state management.

Creating a Plugin

Plugins run before your app mounts:

// plugins/toast.ts
export default defineNuxtPlugin((nuxtApp) => {
  const toast = {
    show(message: string, type: 'success' | 'error' = 'success') {
      // Create and show a toast notification
      const el = document.createElement('div');
      el.className = `toast toast-${type}`;
      el.textContent = message;
      document.body.appendChild(el);
      setTimeout(() => el.remove(), 3000);
    }
  };

  // Make available throughout the app
  return {
    provide: {
      toast
    }
  };
});

Usage in any component:

<script setup>
const { $toast } = useNuxtApp();

const submitForm = async () => {
  await $fetch('/api/submit');
  $toast.show('Form submitted!', 'success');
};
</script>

Output: The $toast utility is available everywhere via useNuxtApp().$toast.

Plugin with Options

Create a configurable plugin:

// plugins/analytics.ts
export default defineNuxtPlugin({
  name: 'analytics',
  hooks: {
    'app:created'() {
      // Initialize analytics when the app starts
      initAnalytics();
    }
  },
  env: { islands: false }  // Don't run in island components
});

Client-Only and Server-Only Plugins

Control where plugins run:

// plugins/client-only.client.ts — runs only on client
export default defineNuxtPlugin(() => {
  if (process.client) {
    // Browser-only code
  }
});

// plugins/server-only.server.ts — runs only on server
export default defineNuxtPlugin(() => {
  if (process.server) {
    // Server-only code
  }
});

Module vs Plugin

Know when to use which:

Common Mistakes

1. Installing modules without restarting: Module changes in nuxt.config.ts require restarting the dev server.
2. Forgetting .client.ts or .server.ts suffix: Without the suffix, plugins run on both client and server. Use suffixes for environment-specific code.
3. Using provide incorrectly: The key name determines the $ prefix. provide: { api: ... } creates $api.
4. Overusing plugins: Not everything needs a plugin. Composables often work better for reusable logic.
5. Module version conflicts: Check module compatibility with your Nuxt version. Use the Nuxt module compatibility table.

Practice Questions

1. How do you add a module to Nuxt 3? Answer: Add the module name to the modules array in nuxt.config.ts. Install it with npm first.

2. What is the difference between a module and a plugin? Answer: Modules configure build-time and server-side behavior. Plugins run at app startup and provide client/server runtime functionality.

3. How do you make a value available across all components? Answer: Use nuxtApp.provide('key', value) in a plugin. Access it with useNuxtApp().$key.

4. How do you create a client-only plugin? Answer: Name the file with .client.ts suffix: plugins/analytics.client.ts.

Challenge

Create a plugin that provides $api utilities (get, post, put, delete) with authentication headers and error handling. Use it across multiple pages.

Mini Project

Create three plugins: an authentication plugin that checks for a token, a notification plugin (toast/alert system), and a formatting plugin with $formatDate, $formatCurrency, and $truncate utilities.

FAQ

What's Next

Learn about Nuxt Server Routes to create backend API endpoints within your Nuxt application.