Addon Manifest Migration

Light Store v24 replaces addon discovery-by-reflection with a manifest. Every addon now declares itself in its own composer.json, and the store wires the addon into Laravel by convention instead of making each addon ship a service provider that does it by hand.

Why it changed

Discovery used to scan every top-level .php file in an addon folder, reflect on each class, and look for a StoreAddon subclass. The identifier, name and version lived as protected properties on that class, so the store had to load and instantiate PHP before it could tell you what an addon even was. A broken addon took the panel down with it, a disabled addon could not name itself, and nothing could be validated before install.

The manifest is read as plain JSON, so the store now knows an addon's identity, its version requirements and its dependencies without executing any of its code.

v23 vs v24

Migrating an addon

{
	"name": "nortexdev/lightstore-points",
	"description": "Reward users with loyalty points on every purchase",
	"version": "2.0.0",
	"type": "library",
	"license": "MIT",
	"homepage": "https://lightstore.nortex.dev",
	"authors": [{ "name": "NorteX" }],
	"require": {
		"php": ">=8.4.0",
		"nortexdev/lightstore": ">=24.0"
	},
	"autoload": {
		"psr-4": {
			"Addon\\PointsAddon\\": ""
		}
	},
	"extra": {
		"laravel": {
			"providers": ["Addon\\PointsAddon\\Providers\\PointsServiceProvider"]
		},
		"lightstore": {
			"identifier": "points",
			"name": "Points",
			"addon": "Addon\\PointsAddon\\PointsAddon"
		}
	}
}

class PointsAddon extends StoreAddon
{
	protected string $identifier = "points";
	protected string $version = "1.1.0";
	protected string $author = "NorteX";

	public function getName(): string
	{
		return __("points::addon.Points");
	}

	public function getDescription(): string
	{
		return __("points::addon.Reward users with loyalty points on every purchase");
	}

	public function getConfig(array $values = []): array { /* ... */ }
}

class PointsAddon extends StoreAddon
{
	public function getConfig(array $values = []): array { /* ... */ }
}

class KnowledgebaseServiceProvider extends ServiceProvider
{
	public function boot(): void
	{
		$routesPath = __DIR__ . "/../routes/web.php";
		if (file_exists($routesPath)) {
			Route::middleware("web")->group(fn() => require $routesPath);
		}

		$viewsPath = __DIR__ . "/../resources/views";
		if (is_dir($viewsPath)) {
			$this->loadViewsFrom($viewsPath, "knowledgebase");
		}

		$langPath = __DIR__ . "/../lang";
		if (is_dir($langPath)) {
			$this->loadTranslationsFrom($langPath, "knowledgebase");
		}

		$migrationsPath = __DIR__ . "/../database/migrations";
		if (is_dir($migrationsPath)) {
			$this->loadMigrationsFrom($migrationsPath);
		}
	}
}

class PointsServiceProvider extends ServiceProvider
{
	public function register(): void {}

	public function boot(): void
	{
		Event::listen(ItemPurchased::class, GrantPointsListener::class);
	}
}

<?php

declare(strict_types=1);

use Addon\PointsAddon\Http\Controllers\PointsController;
use Illuminate\Support\Facades\Route;

Route::middleware("auth")->group(function () {
	Route::get("/profile/points", [PointsController::class, "show"])->name("points.profile");
});

return [
	"Points" => "Points",
	"Reward users with loyalty points on every purchase" => "...", 

	// Settings
	"Earn Multiplier" => "Earn Multiplier",
];

@section('title', __('points::addon.Points') . ' - ' . config('settings.general.site_name')) {/* [!code --] */}
@section('title', __('points::addon.Points') . ' - ' . $generalSettings->site_name) {/* [!code ++] */}

The conventional layout

Lay your addon out like this and the store wires all of it up. Anything that is absent is simply skipped.

Translations load for disabled addons too. The admin panel still offers a Settings button for a disabled addon, and the labels and descriptions on that form come out of getConfig(), where they are usually __() calls against your language files. Without them loaded, that form would render raw language keys.

Manifest reference

autoload.psr-4 is registered against the running Composer class loader at boot. That is what lets an addon installed after the Docker image was built autoload at all, so the prefix has to be correct even though nobody runs composer dump-autoload on the store.

Declaring dependencies

require is validated but never resolved. The store will not download anything on your behalf.

• php, ext-* and lib-* entries are ignored.
• nortexdev/lightstore is treated as a core version constraint. At install the store checks it against its own version with Semver and refuses the addon if it does not satisfy, so ">=24.0" is the right marker for a migrated addon.
• Every other package must either already ship with Light Store, or your addon must carry its own vendor/ directory. If it does, the store requires vendor/autoload.php and skips the dependency check entirely.

Packaging and installing

Zip the addon folder itself, meaning the folder with composer.json at its root. Users install it from Addons then Install addon in the admin panel, which extracts it, validates the manifest, copies it into addons/, runs your migrations by path, enables it and seeds your default settings. Nothing needs rebuilding or restarting.

Installing over an existing copy upgrades it in place and keeps its settings and data. The previous copy is set aside under a dotted folder name, which discovery skips. Your addon folder name has to match /^[A-Za-z0-9][A-Za-z0-9_-]*$/.

Install errors

Styling

Do not ship a stylesheet with your addon. Tailwind expresses breakpoint precedence purely as source order within one @layer utilities, so a second sheet loaded after the theme hoists every utility it repeats above every responsive variant in the theme. That breaks the whole storefront, not just your own pages.

The store's build cannot see your markup either, since addons are kept out of the image build context. Utilities are covered by a generated safelist that is rebuilt when addons are packaged. In practice, stay with utilities the shipped default theme already uses, and reach for a plain style attribute for anything genuinely exotic.