Local Development

This guide walks through setting up the Lunar monorepo inside a Laravel application for local development and contribution.

Lunar v2 is built as a monorepo: a single repository containing several Composer packages (core, admin, filament, panel, stripe, paypal, and more) plus the shared test suite that exercises them.

Prerequisites

PHP 8.4 or higher
A working Laravel application (Laravel 12 or 13)
Composer
Git
Node.js 22+ (only needed for panel frontend work)

Setting Up the Monorepo

1. Create a packages directory

In the root of the Laravel application, create a packages directory to hold the monorepo source code.

mkdir packages

Add packages to the .gitignore file so it is not committed to the application’s repository.

/packages

2. Clone the repository

Fork the lunarphp/lunar repository on GitHub, then clone the fork into the packages directory on the 2.x branch.

cd packages
git clone --branch 2.x https://github.com/YOUR-USERNAME/lunar.git

This places the monorepo at packages/lunar/.

3. Configure Composer

Back in the Laravel application’s composer.json, add a path repository and require the monorepo package.

{
    "repositories": [
        {
            "type": "path",
            "url": "packages/*",
            "symlink": true
        }
    ],
    "minimum-stability": "dev",
    "require": {
        "lunarphp/lunarmono": "*"
    }
}

The lunarphp/lunarmono package is the monorepo root and includes the packages needed to run a store out of the box: the core engine and the Filament admin panel (via its lunarphp/filament bridge).

The symlink option ensures that changes made in the packages/lunar directory are immediately reflected in the application without needing to run composer update after every edit.

4. Install dependencies

Run Composer from the Laravel application’s root directory to install the local packages.

composer update

Once complete, follow the standard installation steps to run migrations and publish assets.

Monorepo Structure

The monorepo contains the following packages under packages/:

Directory	Composer Package	Description
`core`	`lunarphp/core`	Core e-commerce engine: models, actions, pricing, search
`admin`	`lunarphp/admin`	Admin panel resources, built on `lunarphp/filament`
`filament`	`lunarphp/filament`	Bridge that plugs Lunar into any Filament v5 panel
`panel`	`lunarphp/panel`	First-party Inertia + Vue admin panel
`panel-addon-example`	`lunarphp/panel-addon-example`	Example add-on package for the Inertia + Vue panel
`stripe`	`lunarphp/stripe`	Stripe payment driver
`paypal`	`lunarphp/paypal`	PayPal payment driver
`search`	`lunarphp/search`	Scout-based search: database, Meilisearch, and Typesense engines
`meilisearch`	`lunarphp/meilisearch`	Meilisearch add-on
`table-rate-shipping`	`lunarphp/table-rate-shipping`	Table rate shipping method
`upgrade`	`lunarphp/upgrade`	Rector rules and data migrations for v1 to v2 upgrades
`demo-data`	`lunarphp/demo-data`	Seeds a reproducible demo store

PHP tests for each package live under the top-level tests/ directory, grouped by package name (tests/core, tests/admin, and so on).

Running Tests

Lunar uses Pest for its PHP test suite. Each package has its own Pest testsuite, defined in phpunit.xml, and CI runs them one at a time rather than as a single combined pass. Run tests from the monorepo root at packages/lunar/, matching CI:

cd packages/lunar
vendor/bin/pest --testsuite core --parallel
vendor/bin/pest --testsuite admin --parallel

The full list of testsuites in the CI matrix is core, admin, panel, filament, shipping, stripe, paypal, search, and upgrade. A demo-data testsuite also exists but is not part of the CI matrix. To run the full local sweep:

for s in core admin panel filament shipping stripe paypal search upgrade; do
  vendor/bin/pest --testsuite "$s" --parallel || break
done

Cross-database tests run as a group rather than a testsuite, against MySQL and PostgreSQL:

vendor/bin/pest --group=cross-db --parallel --do-not-fail-on-empty-test-suite

All existing tests must continue to pass before submitting a pull request.

Panel Frontend

The Inertia + Vue panel (packages/panel) has its own dependency tree, separate from the monorepo’s root npm workspace, and needs its own install.

cd packages/panel
npm install
npm test          # vitest
npm run type-check
npm run build

The example add-on package builds through the npm workspace at the monorepo root instead:

npm install
npm run build --workspace @lunarphp/panel-addon-example

Code Style and Static Analysis

Lunar follows the Laravel coding style and uses Laravel Pint for enforcement, and PHPStan (via Larastan) for static analysis. Run both from the monorepo root before committing changes.

vendor/bin/pint --dirty
vendor/bin/phpstan analyse --no-progress

Next Steps

With local development set up, see the Contributing guide for information on coding standards, submitting pull requests, and reporting bugs.

Overview

Setup & Configuration

Prerequisites

Setting Up the Monorepo

1. Create a packages directory

2. Clone the repository

3. Configure Composer

4. Install dependencies

Monorepo Structure

Running Tests

Panel Frontend

Code Style and Static Analysis

Next Steps

​Prerequisites

​Setting Up the Monorepo

​1. Create a packages directory

​2. Clone the repository

​3. Configure Composer

​4. Install dependencies

​Monorepo Structure

​Running Tests

​Panel Frontend

​Code Style and Static Analysis

​Next Steps

Prerequisites

Setting Up the Monorepo

1. Create a packages directory

2. Clone the repository

3. Configure Composer

4. Install dependencies

Monorepo Structure

Running Tests

Panel Frontend

Code Style and Static Analysis

Next Steps