Building a Custom Plugin in nopCommerce (Step-by-Step Guide)

Sangeet Shah
18h
111
0
0
25
Blog

🧩 Introduction

nopCommerce is one of the most powerful open-source eCommerce platforms built on ASP.NET Core.
Its plugin-based architecture makes it easy to extend or customize the system without touching the core source code, which means safer upgrades and cleaner maintenance.

In this article, we’ll walk through a step-by-step guide to building a custom plugin in nopCommerce — from project setup to installation and deployment.

By the end, you’ll have a working plugin that can integrate new features into your nopCommerce store.

🧰 Prerequisites

Before you begin, make sure you have:

nopCommerce 4.8 source code
Visual Studio 2022 or later
.NET 8 SDK installed
Basic understanding of C#, dependency injection, and ASP.NET Core MVC

🪜 Step 1. Understanding nopCommerce Plugin Structure

All plugins in nopCommerce live inside the /Plugins directory.

Each plugin typically includes:

/Plugins
   /YourCompany.PluginName
      /Controllers
      /Models
      /Views
      /Data
      /Services
      /plugin.json
      YourCompany.PluginName.csproj

Key file
plugin.json — this tells nopCommerce how to load your plugin.

Example

{
  "Group": "Custom",
  "FriendlyName": "Hello World Plugin",
  "SystemName": "YourCompany.HelloWorld",
  "Version": "1.00",
  "SupportedVersions": [ "4.80" ],
  "Author": "Sangeet Shah",
  "DisplayOrder": 1
}

🪄 Step 2. Create a New Plugin Project

Inside the /Plugins folder, create a new folder:
```
YourCompany.HelloWorld
```
Add a new Class Library project named:
```
YourCompany.HelloWorld.csproj
```
Edit the .csproj file and reference nopCommerce core libraries:

<Project Sdk="Microsoft.NET.Sdk.Web">

  <PropertyGroup>
    <TargetFramework>net8.0</TargetFramework>
    <AddRazorSupportForMvc>true</AddRazorSupportForMvc>
  </PropertyGroup>

  <ItemGroup>
    <ProjectReference Include="..\..\Presentation\Nop.Web.Framework\Nop.Web.Framework.csproj" />
    <ProjectReference Include="..\..\Libraries\Nop.Core\Nop.Core.csproj" />
    <ProjectReference Include="..\..\Libraries\Nop.Services\Nop.Services.csproj" />
  </ItemGroup>

</Project>

Add plugin.json as shown in Step 1.

🧱 Step 3. Create the Plugin Main Class

Every nopCommerce plugin must inherit from BasePlugin.

Create a file named HelloWorldPlugin.cs:

using Nop.Core;
using Nop.Services.Plugins;
using Nop.Web.Framework.Menu;

namespace YourCompany.HelloWorld
{
    public class HelloWorldPlugin : BasePlugin, IAdminMenuPlugin
    {
        private readonly IWebHelper _webHelper;

        public HelloWorldPlugin(IWebHelper webHelper)
        {
            _webHelper = webHelper;
        }

        public override string GetConfigurationPageUrl()
        {
            return $"{_webHelper.GetStoreLocation()}Admin/HelloWorld/Configure";
        }

        public override void Install()
        {
            // You can add initialization logic here (like DB setup)
            base.Install();
        }

        public override void Uninstall()
        {
            // Cleanup logic (like remove settings or data)
            base.Uninstall();
        }

        public void ManageSiteMap(SiteMapNode rootNode)
        {
            var menuItem = new SiteMapNode
            {
                Title = "Hello World",
                Visible = true,
                Url = $"{_webHelper.GetStoreLocation()}Admin/HelloWorld/Configure"
            };

            rootNode.ChildNodes.Add(menuItem);
        }
    }
}

This registers a simple admin menu item for your plugin.

🧑‍💻 Step 4. Create a Controller and View

Create a controller in /Controllers/HelloWorldController.cs:

using Microsoft.AspNetCore.Mvc;
using Nop.Web.Framework.Controllers;
using Nop.Web.Framework.Mvc.Filters;

namespace YourCompany.HelloWorld.Controllers
{
    [AuthorizeAdmin]
    [Area(AreaNames.Admin)]
    public class HelloWorldController : BasePluginController
    {
        [HttpGet]
        public IActionResult Configure()
        {
            ViewBag.Message = "Hello from your custom nopCommerce plugin!";
            return View("~/Plugins/YourCompany.HelloWorld/Views/Configure.cshtml");
        }
    }
}

Now create a view in /Views/Configure.cshtml:

@{
    Layout = "_AdminLayout";
}

<div class="content-header clearfix">
    <h1 class="pull-left">Hello World Plugin</h1>
</div>

<div class="content">
    <p>@ViewBag.Message</p>
</div>

⚙️ Step 5. Build and Deploy the Plugin

Build the solution in Visual Studio.
The output will be copied to:
```
/Presentation/Nop.Web/Plugins/bin/
```
In the nopCommerce admin panel, go to:
```
Configuration → Local Plugins
```
Click Upload plugin and/or theme → Select your plugin ZIP → Upload and Install
Restart the application, and you should now see your “Hello World” plugin in the admin menu!

🧠 Step 6. Add Custom Settings (Optional)

You can store configuration settings using ISettingService.

public class HelloWorldSettings : ISettings
{
    public string GreetingText { get; set; }
}

await _settingService.SaveSettingAsync(new HelloWorldSettings { GreetingText = "Welcome!" });

Then retrieve:

var settings = await _settingService.LoadSettingAsync<HelloWorldSettings>();

🧩 Step 7. Best Practices for Plugin Development

Always avoid modifying core code — use dependency injection or event consumers instead.
Use async/await for all service calls.
Keep your plugin modular and self-contained.
Use StoreMapping and ACL (Access Control List) for store-specific behavior.
Always implement Install() / Uninstall() properly to handle database objects and settings.

🧾Example Use Cases

Here are some real-world examples of plugins you can build:

🧾 Custom invoice generator
📦 Shipping or payment gateway integration
📈 Google Tag Manager / Analytics tracker
📬 Klaviyo or Mailchimp email marketing connector
💬 AI-powered chatbot widget
⚙️ Rate limiting or caching layer plugin

Each can follow the same plugin-based pattern described above.

🏁 Conclusion

nopCommerce’s plugin system is one of its most powerful features, allowing you to extend functionality without touching the core codebase.

By following this guide, you’ve learned how to:

Create the plugin structure
Register it with nopCommerce
Add a controller, view, and configuration page
Deploy and test your plugin

Now you can confidently build your own custom plugins and take full advantage of nopCommerce’s modular architecture. 🚀