Medusa Plugin Brand

Features

A comprehensive brand management solution for Medusa v2 commerce platforms:

• ✅ Brand Entity & Database - Full database model with migrations
• ✅ Brand CRUD API - RESTful endpoints for brand management
• ✅ Admin Dashboard UI - Custom pages for viewing and managing brands
• ✅ Product-Brand Linking - Automatic linking between products and brands
• ✅ Admin Brand List Page - Paginated table view of all brands
• ✅ Admin Brand Detail Page - View individual brand information
• ✅ Product Widget - Display brand information on product detail pages
• 🔄 Brand Select Picker - Assign/change brands when editing products (Coming Soon)
• 🔄 Brand Creation Form - Create brands directly from admin UI (Coming Soon)

Installation

1. Install the Plugin

npm install @erulabs/medusa-plugin-brand
# or
pnpm add @erulabs/medusa-plugin-brand
# or
yarn add @erulabs/medusa-plugin-brand
# or
bun add @erulabs/medusa-plugin-brand

2. Add to Medusa Configuration

In your medusa-config.ts or medusa-config.js:

import { defineConfig } from "@medusajs/utils";

export default defineConfig({
  // ... other config
  plugins: [
    {
      resolve: "@erulabs/medusa-plugin-brand",
      options: {},
    },
  ],
});

3. Run Migrations

npx medusa db:migrate

4. Start Development Server

npx medusa develop

Usage

API Endpoints

Create Brand

POST /admin/brands
Content-Type: application/json
Authorization: Bearer <token>

{
  "name": "Nike"
}

List Brands

GET /admin/brands?limit=20&offset=0
Authorization: Bearer <token>

Get Brand by ID

GET /admin/brands/{id}
Authorization: Bearer <token>

Assign Brand to a product

POST /admin/brands/assign-product
Content-Type: application/json
Authorization: Bearer <token>

{
  "product_id": "prod_id",
  "brand_id": "br_id",
  "old_brand_id": "old_brand_id" // If there was an existing linking
}

Linking Brands to Products

When creating products, include the brand_id in additional_data:

import { createProductsWorkflow } from "@medusajs/medusa/core-flows";

// In your custom workflow or API route
await createProductsWorkflow(container).run({
  input: {
    products: [
      {
        title: "Air Max 90",
        handle: "air-max-90",
        // ... other product fields
      }
    ],
    additional_data: {
      brand_id: "brand_123"
    }
  }
});

Admin Dashboard

After installation, access the brand management UI:

1. Navigate to Products → Brands in the admin dashboard
2. View all brands in a paginated table
3. Click on a brand to view details and associated products
4. Brand information is displayed on product detail pages

Brand Entity

The brand entity includes the following fields:

| Field | Type | Description | |-------|------|-------------| | id | string | Primary key | | name | string | Brand name (required) | | handle | string | Unique slug identifier (auto-generated) | | description | string | Optional brand description | | created_at | datetime | Creation timestamp | | updated_at | datetime | Last update timestamp | | deleted_at | datetime | Soft delete timestamp |

Project Structure

packages/brand/
├── src/
│   ├── admin/                    # Admin dashboard customizations
│   │   ├── routes/
│   │   │   └── brands/          # Brand management pages
│   │   ├── widgets/
│   │   │   └── product-brand.tsx # Product page widget
│   │   └── lib/
│   │       └── sdk.ts           # Admin SDK configuration
│   ├── api/
│   │   └── admin/
│   │       └── brands/          # REST API endpoints
│   ├── modules/
│   │   └── brand/
│   │       ├── models/
│   │       │   └── brand.ts     # Brand entity definition
│   │       ├── migrations/      # Database migrations
│   │       ├── service.ts       # Brand module service
│   │       └── index.ts         # Module exports
│   ├── workflows/
│   │   ├── hooks/
│   │   │   └── created-product.ts # Product creation hook
│   │   ├── steps/
│   │   │   └── create-brand.ts    # Brand creation step
│   │   └── create-brand.ts        # Brand creation workflow
│   └── links/
│       └── product-brand.ts       # Product-Brand relationship
└── package.json

Feature Checklist

✅ Implemented Features

• [x] Core Module

  • [x] Brand entity with id, name, handle, description
  • [x] Database migration with proper indexing
  • [x] Module service with CRUD operations
  • [x] Soft delete support

• [x] API Endpoints

  • [x] POST /admin/brands - Create brand
  • [x] GET /admin/brands - List brands (paginated)
  • [x] GET /admin/brands/:id - Get brand by ID
  • [x] Request validation with Zod schemas
  • [x] Middleware for query/body transformation

• [x] Workflows & Hooks

  • [x] Create brand workflow with compensation
  • [x] Product creation hook for automatic brand linking
  • [x] Workflow rollback support

• [x] Module Links

  • [x] Product-Brand relationship definition
  • [x] Automatic linking on product creation

• [x] Admin Dashboard

  • [x] Brands list page with DataTable
  • [x] Brand detail page
  • [x] Product brand display widget
  • [x] Navigation under Products section
  • [x] Custom SDK for API communication

🚧 Planned Features

• [ ] Brand Management UI

  • [ ] Brand creation form/modal
  • [ ] Brand edit form
  • [ ] Brand deletion with confirmation
  • [ ] Bulk actions for brands

• [ ] Product Integration

  • [ ] Brand select picker in product edit form
  • [ ] Update product brand workflow hook
  • [ ] Brand filtering in product list
  • [ ] Brand search in product forms

• [ ] Enhanced Brand Features

  • [ ] Brand logo upload
  • [ ] Brand metadata fields
  • [ ] Brand SEO fields
  • [ ] Brand collections/grouping

• [ ] API Enhancements

  • [ ] PATCH /admin/brands/:id - Update brand
  • [ ] DELETE /admin/brands/:id - Delete brand
  • [ ] Batch operations
  • [ ] Advanced filtering & sorting

• [ ] Admin UX Improvements

  • [ ] Brand autocomplete in forms
  • [ ] Brand analytics dashboard
  • [ ] Product count per brand display
  • [ ] Quick brand creation from product form

Development

Prerequisites

• Node.js >= 20
• pnpm >= 10
• Medusa v2.4.0+

Local Development

# Clone the repository
git clone https://github.com/erulabs/medusa-plugins.git
cd medusa-plugins

# Install dependencies
pnpm install

# Build the plugin
cd packages/brand
pnpm build

# Run in development mode
pnpm dev

Testing

# Run tests
pnpm test

# Run with coverage
pnpm test:coverage

Building for Production

pnpm build

This generates the compiled plugin in the .medusa/server directory.

Compatibility

• Medusa Version: >= 2.4.0
• Node.js: >= 20
• Database: PostgreSQL (recommended), SQLite for development

Dependencies

Peer Dependencies

• @medusajs/medusa - ^2.13.3
• @medusajs/framework - ^2.13.3
• @medusajs/admin-sdk - ^2.13.3
• @medusajs/ui - ^4.0.25
• @medusajs/icons - ^2.13.3

Runtime Dependencies

• @medusajs/js-sdk - ^2.13.3
• @tanstack/react-query - ^5.64.2

Contributing

Contributions are welcome! Please follow these steps:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Please read our Contributing Guide for details on our code of conduct and development process.

License

Distributed under the MIT License. See LICENSE for more information.

Support

• Documentation: https://docs.medusajs.com
• Discord: https://discord.gg/medusajs
• GitHub Issues: https://github.com/erulabs/medusa-plugins/issues
• Twitter: https://twitter.com/medusajs

About EruLabs

EruLabs builds high-quality plugins and extensions for the Medusa commerce platform. We're committed to making ecommerce development faster, easier, and more accessible.

Explore our other plugins and tools at github.com/erulabs.