# qoliber/nebula-admin-theme

> Nebula admin theme and modules for Magento 2 / Mage-OS. Targets Magento 2.4.7+ (or Mage-OS 2.0+) on PHP 8.1+.

`composer require qoliber/nebula-admin-theme`

Canonical URL: https://packagento.com/qoliber/nebula-admin-theme

## At a glance

- **Vendor**: qoliber (https://packagento.com/qoliber.md)
- **Latest version**: 0.9.0 — released 2026-06-04
- **Pricing**: Free
- **Package type**: Magento 2 component
- **Status**: active, accepting new buyers

## Installation

Packagento is licence-gated, so even free packages need a licence on a project before Composer can resolve them.

1. **Sign in or create an account** at https://packagento.com/customer/account/.

2. **Add the package to your account.** Open https://packagento.com/qoliber/nebula-admin-theme and complete the free checkout. A licence is minted automatically.

3. **Create or pick a project, then activate the licence on it.**
   - Projects represent the Magento installs you deploy to. Manage them at https://packagento.com/projects/.
   - Activate the new licence on the project you'll deploy this package to. Activation is what generates the Composer credentials scoped to that project.

4. **Add the project credentials to your Magento codebase.**

   Grab the project's public + private key from https://packagento.com/projects/ (open the project, then its Credentials tab), and add them to `auth.json`:

   ```json
   {
     "http-basic": {
       "packagento.com": {
         "username": "ppk_live_...",
         "password": "psk_live_..."
       }
     }
   }
   ```

   Add the Packagento Composer repository to `composer.json`:

   ```json
   {
     "repositories": [
       { "type": "composer", "url": "https://packagento.com" }
     ]
   }
   ```

5. **Install and apply.**

   ```bash
   composer require qoliber/nebula-admin-theme:*
   bin/magento setup:upgrade
   bin/magento setup:di:compile
   bin/magento cache:flush
   ```

## What it does

Nebula admin theme and modules for Magento 2 / Mage-OS. Targets Magento 2.4.7+ (or Mage-OS 2.0+) on PHP 8.1+.

## README

> **Replace Magento's legacy admin theme — bring it into the 21st century.**

Nebula modernizes the Magento Admin with a faster interface, cleaner workflows,
dark mode, and developer-friendly customization — **without forcing you to
replace Magento itself.** It runs alongside your existing store on
Magento 2.4.7+ (or Mage-OS 2.0+) and PHP 8.1+.

---

### Why Nebula

| | |
|---|---|
| ⚡ **Faster** | Native ES modules replace RequireJS; vanilla JS replaces jQuery; Alpine.js 3 replaces KnockoutJS. |
| 🎨 **Beautiful** | Tailwind CSS 4 styling, dark mode, and 18 built-in skins for client-specific branding. |
| 🧩 **Composable** | JSON-driven forms and grids plus reusable snippets — clearer definitions in place of sprawling XML UI Components. |
| 🛠️ **Developer-friendly** | A simpler, more maintainable admin stack. Easier grid and form extensions, fewer moving parts. |
| 🚀 **Zero build step** | Ships with compiled assets — install and go. |

#### Who it's for

- **Store owners & admin teams** — faster daily order, catalog, and content
  workflows, with dark mode and pinned navigation. Modernize the back office
  without changing your commerce platform.
- **Developers** — a cleaner admin architecture with JSON definitions instead
  of XML UI patterns, and straightforward extension points.
- **Agencies** — quicker admin improvements, client branding via skins, and
  lower back-office customization costs.

---

### Highlights

- **JSON-driven UI** — admin forms and grids defined as JSON, with a library of
  reusable composable snippets.
- **Modern frontend** — Alpine.js 3, Tailwind CSS 4, native ES modules, no
  RequireJS/KnockoutJS/jQuery.
- **Dark mode + skins** — multiple built-in themes; brand per client.
- **Focused modules** — a clean, modular package (see below) you can adopt
  incrementally.
- **Well tested** — extensive PHPUnit and Vitest coverage, plus bridge tests for
  third-party compatibility.

---

### Installation

```bash
composer require qoliber/nebula-admin-theme
bin/magento setup:upgrade
bin/magento setup:di:compile
bin/magento setup:static-content:deploy -f
bin/magento cache:flush
```

Then activate the **Nebula** theme under
**Stores → Configuration → Design** (adminhtml), or assign it as the admin
theme for your environment.

#### Requirements

- Magento **2.4.7+** or Mage-OS **2.0+**
- PHP **8.1+**

---

### Modules

This package ships the following focused modules:

| Module | Responsibility |
|---|---|
| `Qoliber_Nebula` | Package umbrella + shared configuration |
| `Qoliber_NebulaComponent` | Core component framework (definitions, snippets, registries) |
| `Qoliber_NebulaForm` | JSON-driven admin forms |
| `Qoliber_NebulaGrid` | JSON-driven admin grids |
| `Qoliber_NebulaTheme` | Theme integration + data providers |
| `Qoliber_NebulaMenu` | Admin navigation / menu |
| `Qoliber_NebulaSkin` | Tailwind CSS styling and skins |
| `Qoliber_NebulaMedia` | Media browser / picker |
| `Qoliber_NebulaQuill` | Quill WYSIWYG editor integration |
| `Qoliber_NebulaDirective` | Widget / directive support |
| `Qoliber_NebulaStore` | Stores, websites, and design-config screens |
| `Qoliber_NebulaSystem` | System pages and tooling |
| `Qoliber_NebulaReports` | Reports grids |
| `Qoliber_NebulaCurrency` | Currency screens |
| `Qoliber_NebulaUser` | Admin users and roles |
| `Qoliber_NebulaUiRemoval` | Disables Magento's UI Component reader/generator where Nebula replaces it |

---

### License

Nebula is released under the **Nebula Community License (NCL)** — a
source-available license. See [LICENSE.md](LICENSE.md) for the full terms.

---

### Brought to you by

[**qoliber**](https://qoliber.com) and [**Siteation**](https://siteation.dev/)

## Changelog

All notable changes to the Nebula admin theme are recorded here.
The format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/);
the project aims to follow Semantic Versioning.

### [0.9.0]

#### Added

- **Five modules promoted to the public package**: `Qoliber_NebulaCurrency`,
  `Qoliber_NebulaDirective`, `Qoliber_NebulaReports`, `Qoliber_NebulaSystem`,
  and `Qoliber_NebulaUser`. The package now ships 16 modules plus the theme.

#### Changed

- `registration.php` updated to list the published modules.
- Version bumped to `0.9.0`.

#### Security

- **Grid request hardening** — whitelist filter and sort columns against the
  grid definition and clamp `pageSize` (`MAX_PAGE_SIZE = 200`) across all data
  providers (`CollectionProvider`, `ProductProvider`, `CustomerGridProvider`,
  `SalesRuleCouponsGridProvider`, `AgreementGridProvider`, `AttributeSetProvider`).
- **Media browser** — `MediaPicker` rejects path-traversal segments and asserts
  the resolved file stays under the media root before deletion.
- **Toast notifications** — render admin messages as text (`textContent`),
  closing a DOM-XSS vector.
- `DefinitionAccessControl` treats an empty `acl` string as unset and falls back
  to `Magento_Backend::admin` (default-deny).

#### Internal

- Snippet templates no longer use `ObjectManager::getInstance()`; ViewModels are
  injected via `SnippetViewModelRegistry` (or layout XML), throwing if a
  `view_model` is missing instead of silently service-locating.
- Complete PHPDoc coverage on changed PHP (FQDN `@param`/`@return`).

### [0.8.0]

#### Added

- Initial public release.

## Recent Versions

| Version | Released |
|---|---|
| 0.9.0 | 2026-06-04 |

## Dependencies

### Require

| Package | Constraint |
|---|---|
| magento/framework | ^103.0 |
| php | ^8.1 |

## Licence and pricing

Free. A licence is still minted on checkout and bound to your project for Composer access — no payment step.

Refundable within 14 days of first purchase via https://packagento.com/account/refunds/.

## Install via Claude Code or any MCP client

The Packagento MCP server can run the licence + project + Composer steps above in one tool call:

```
purchase_and_install_packages(
  composer_names=["qoliber/nebula-admin-theme"],
  project_id="proj_xxx"
)
```

This handles cart, checkout, licence minting, project activation, and writes auth.json credentials. Connect a client with `claude mcp add packagento https://mcp.packagento.com`. Full setup at https://packagento.com/docs/mcp-setup.

## Vendor

qoliber is a Magento 2 vendor on Packagento. See https://packagento.com/qoliber.md for their full catalogue.