Repository: bagisto/bagisto

Stars: 26435

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Bagisto 2.4.x - open-source Laravel 12 e-commerce platform. PHP 8.3+, Vue.js 3, Tailwind CSS 3, Vite 5.

Common Commands

Development

bash

composer install                # Install PHP dependencies
php artisan bagisto:install     # Full installation (migrations, seeders, assets)
php artisan serve               # Start PHP dev server
php artisan optimize:clear      # Clear all caches (run after config/code changes)

Testing

bash

vendor/bin/pest                                         # Run all tests
vendor/bin/pest --testsuite="Admin Feature Test"        # Run a specific test suite
vendor/bin/pest packages/Webkul/Admin/tests/Feature     # Run tests in a directory
vendor/bin/pest --filter="test name"                    # Run a single test by name

Test suites defined in phpunit.xml: Admin Feature, Core Unit, Customer Unit, DataGrid Unit, Installer Feature, PayU Unit/Feature, Razorpay Unit/Feature, Shop Feature, Stripe Unit/Feature.

Tests use Pest 3 with package-specific TestCase classes bound in tests/Pest.php. Each package's tests live in packages/Webkul/<Package>/tests/.

E2E Tests (Playwright)

E2E tests are run from within each package directory. Each package has its own Playwright config and tests:

Admin:

bash

cd packages/Webkul/Admin
npm install
npx playwright install --with-deps chromium
npx playwright test --config=tests/e2e-pw/playwright.config.ts

Shop:

bash

cd packages/Webkul/Shop
npm install
npx playwright install --with-deps chromium
npx playwright test --config=tests/e2e-pw/playwright.config.ts

Tests require a running Laravel server (php artisan serve) and seeded database. Set BASE_URL env var if not using default.

Code Style

bash

vendor/bin/pint             # Fix PHP code style (Laravel Pint)
vendor/bin/pint --test      # Check style without fixing

Translations

When adding new translation keys, always provide translations for all locales in the package's Resources/lang/ directory. Verify with:

bash

php artisan bagisto:translations:check

Architecture

Modular Package System

All core functionality lives in packages/Webkul/ (~42 packages). Each package is a self-contained Laravel package with its own models, controllers, routes, views, migrations, and service providers.

Dual registration: Each package registers in two places:
1. bootstrap/providers.php - Main ServiceProvider (routes, views, events, config)
2. config/concord.php - ModuleServiceProvider (Konekt Concord model/enum registration)

Key Design Patterns

Repository Pattern: All database access goes through repositories (Prettus L5 Repository). Interfaces in Contracts/, implementations in Repositories/. Never use models directly for queries in controllers.

Proxy Pattern: Models have Proxy classes (e.g., ProductProxy, CategoryProxy) enabling model substitution without modifying core code. Always reference proxies when type-hinting across packages.

Event-Driven Extensibility: The framework fires events at key lifecycle points. Extend behavior via listeners rather than modifying core packages.

Package Anatomy

text

packages/Webkul/<Package>/src/
├── Config/           # system.php (admin settings), admin-menu.php, acl.php
├── Database/         # Migrations/, Seeders/, Factories/
├── Http/Controllers/ # Separate Admin/ and Shop/ controller directories
├── Models/           # Eloquent models + Proxy classes
├── Repositories/     # Data access layer
├── Contracts/        # Interfaces for models and repositories
├── Resources/
│   ├── views/        # Blade templates (admin/, shop/)
│   ├── lang/         # Localization (translatable strings)
│   └── assets/       # CSS/JS source files
├── Routes/           # admin-routes.php, shop-routes.php, api.php
├── Providers/        # ServiceProvider + ModuleServiceProvider
└── Listeners/        # Event listeners

Frontend Assets

Admin, Shop, and Installer each have independent Vite builds. Run npm install and npm run dev/npm run build from within the respective package directory:
- Admin: packages/Webkul/Admin/ builds to public/themes/admin/default/build/
- Shop: packages/Webkul/Shop/ builds to public/themes/shop/default/build/
- Installer: packages/Webkul/Installer/

Vue 3 components are used within Blade templates via @pushOnce('scripts') / Blade component slots.

Naming Conventions

- Namespace: Webkul\<PackageName> (e.g., Webkul\Product)
- Routes: Separate admin-routes.php and shop-routes.php per package
- Models: Singular (Product, Category)
- Repositories: <Model>Repository (e.g., ProductRepository)
- Controllers: <Model>Controller in Http/Controllers/Admin/ or Shop/

Adding a New Package

1. Create packages/Webkul/<Name>/src/ with the standard structure
2. Add PSR-4 namespace to root composer.json autoload
3. Register ServiceProvider in bootstrap/providers.php
4. Register ModuleServiceProvider in config/concord.php
5. Run composer dump-autoload && php artisan optimize:clear

Or use: php artisan package:make Webkul/<Name> (requires bagisto/bagisto-package-generator)

CI Pipeline

- pest_tests.yml: Pest tests on PHP 8.3 + MySQL 8.0
- pint_tests.yml: Code style checks with Laravel Pint
- admin_playwright_tests.yml / shop_playwright_tests.yml: E2E tests (6 parallel shards)
- translation_tests.yml: Translation file validation

README.md

➡️ <a href="https://bagisto.com/en/">Website</a> | <a href="https://devdocs.bagisto.com/">Documentation</a> | <a href="https://devdocs.bagisto.com/2.3/introduction/installation.html#installation">Installation Guide</a> | <a href="https://devdocs.bagisto.com/2.3/introduction/docker.html">Docker Installation</a> | <a href="https://forums.bagisto.com/">Forums</a> | <a href="https://www.facebook.com/groups/bagisto/">Community</a> ⬅️

Introduction

Bagisto is an opensource laravel eCommerce framework built on some of the hottest technologies such as Laravel (a PHP framework) and Vue.js a progressive Javascript framework.

Bagisto can help you cut down your time, cost, and workforce for building online stores or migrating from physical stores to the ever-demanding online world. Your business—whether small or huge—can benefit. The best part, it's straightforward to set it up!

!Repo Stats

Getting Started

!Getting Started

Install Bagisto with or without Composer (Check Requirement Details)

Follow the Getting Started with Bagisto Tutorial

You can browse through the Free Live Demo

☁️ Cloud Installation via Amazon AMI

You can also deploy Bagisto quickly using our pre-configured Amazon Machine Image (AMI) available on the AWS Marketplace:

👉 Launch Bagisto on AWS

This AMI allows you to get started with Bagisto on a cloud environment without manual setup. Ideal for scalable production or testing environments.

Accelerate Your Online Store Launch with the Bagisto Starter Pack!

Empower your e-commerce journey with the Bagisto Starter Pack, streamlining setup and integration for a seamless online store launch. Get ready to unlock success in the digital marketplace!

Open Source B2B eCommerce Platform

The B2B eCommerce Platform enhances your Bagisto store with advanced Business-to-Business (B2B) features. It enables company-based purchasing, multi-user access, quote negotiation, and procurement management — empowering businesses to handle B2B workflows efficiently within a single platform.

!Bagisto B2B Ecommerce Image

Multi Vendor Marketplace

Multi Vendor Marketplace transforms a standard store into a complete marketplace, allowing the admin to manage sellers, commissions, product approvals, and order handling, while giving vendors a dedicated dashboard to manage their catalog, orders, and transactions.

!Multi Vendor Marketplace Image

Multi Tenant eCommerce

Multi Tenant eCommerce in Bagisto allows businesses to build a SaaS-based marketplace platform where multiple vendors or merchants can create and manage their own individual stores under a single system.

!Multi Tenant eCommerce Image

POS

Point of Sale system manages retail operations efficiently, handling inventory management and fast customer checkout for your store.

!POS Image

Headless Commerce

The power of headless laravel commerce now comes to Bagisto enabling you to experience seamless and easily scalable storefront performance. Backed by some of the hottest tech stacks, Bagisto commerce can now be used to build powerful headless commerce solutions offering blazing-fast speed and easy customization powered by Next.js

Next.js Commerce

!Next.js Logo

Develop and deploy your next headless commerce storefronts with Next JS and Bagisto: https://github.com/bagisto/nextjs-commerce

Open Source Mobile eCommerce

Revolutionize Your Online Store with Bagisto's Open Source eCommerce Mobile

!Mobile View Example Screens

Mobile eCommerce powered by Flutter & Laravel: https://github.com/bagisto/opensource-ecommerce-mobile-app

AI Powered eCommerce

You can integrate popular large language models like GPT-5, Gemini 3, Mistral, and LLaMA 4, Grok (xAI),GLM 4.6,Kimi-K2, Qwen 3, Deepseek etc to build AI-powered eCommerce applications with Bagisto. Some of the popular use cases where you can make use of LLMs to build AI apps are chatbot, automated product descriptions, customer support, search, and recommendations.

!AI Powered eCommerce Examples

You can incorporate LLM API with your bagisto applications to send and receive queries and ensure proper error handling and rate limiting to prevent overuse of the API

Decentralised eCommerce

Build decentralised applications with Bagisto on popular blockchains like Ethereum and Solana by integrating smart contracts with the eCommerce platform. You can have decentralised marketplaces, NFT marketplaces, and decentralised e-signing with the laravel eCommerce system.

!Decentralized Ecommerce Example Screens

Commerce For Every Need

!Commerce Store Examples

With Bagisto, you can easily create use cases for various commerce needs like Marketplaces, PWA, Native Mobile Apps, Multi-Tenants systems, Blockchain and many more.

Built In Extensions

!200+ Prebuilt Extensions

Make use of 100+ Bagisto pre-built extensions from Bagisto Extension Markeptlace

Community

!Forum and Facebook Communities

Get Bagisto support on Facebook Group and Forum
Would like to help us build the most developer-friendly E-Commerce platform? Start by reading our Contributing Guide!

License

Bagisto is a fully open-source Laravel eCommerce framework that will always remain free under the MIT License.

Security Vulnerabilities

If you think that you have found a security issue in Bagisto, please do not use the issue tracker and do not post it publicly. Instead, all security issues must be sent to mailto:[email protected].

Contributors

This project is on Open Collective, and it exists thanks to the people who contribute.

Backers

Thank you to all our backers! 🙏

Repository: bagisto/bagisto

Stars: 26435

CLAUDE.md Copy Chapter

CLAUDE.md

Project Overview Copy Chapter

Common Commands Copy Chapter

Development Copy Section

Testing Copy Section

E2E Tests (Playwright) Copy Section

Code Style Copy Section

Translations Copy Section

Architecture Copy Chapter

Modular Package System Copy Section

Key Design Patterns Copy Section

Package Anatomy Copy Section

Frontend Assets Copy Section

Naming Conventions Copy Section

Adding a New Package Copy Section

CI Pipeline Copy Chapter

README.md Copy Chapter

Introduction

Getting Started

☁️ Cloud Installation via Amazon AMI Copy Chapter

Accelerate Your Online Store Launch with the Bagisto Starter Pack!

Open Source B2B eCommerce Platform

Multi Vendor Marketplace

Multi Tenant eCommerce

POS

Headless Commerce

Next.js Commerce Copy Chapter

Open Source Mobile eCommerce

AI Powered eCommerce

Decentralised eCommerce

Commerce For Every Need

Built In Extensions

Community

License

Security Vulnerabilities

Contributors

Backers

Sponsors

CLAUDE.md

Project Overview

Common Commands

Development

Testing

E2E Tests (Playwright)

Code Style

Translations

Architecture

Modular Package System

Key Design Patterns

Package Anatomy

Frontend Assets

Naming Conventions

Adding a New Package

CI Pipeline

README.md

☁️ Cloud Installation via Amazon AMI

Next.js Commerce