Documentation

Getting Started

Install Nebula on Magento 2 or MageOS. Replace the entire legacy admin stack in under 5 minutes.

Prerequisites

Magento 2.4.7+ or MageOS 2.0+

Open Source or Commerce

PHP 8.1+

Constructor property promotion, readonly

Node.js 20+

Build only; compiled assets are committed

Composer 2.x

Dependency management

Installation

Install via Composer

Require Nebula from Packagist — the metapackage pulls in the admin theme and every module.

terminal

composer require qoliber/nebula-admin-theme

Installs under vendor/qoliber/nebula-admin-theme/ and registers the theme (Qoliber/Nebula) plus all Qoliber_Nebula* modules. See packagist.org/packages/qoliber/nebula-admin-theme.

Enable all Nebula modules

terminal

php bin/magento module:enable \
  Qoliber_Nebula \
  Qoliber_NebulaComponent \
  Qoliber_NebulaGrid \
  Qoliber_NebulaForm \
  Qoliber_NebulaSkin \
  Qoliber_NebulaMenu \
  Qoliber_NebulaUiRemoval \
  Qoliber_NebulaTheme \
  Qoliber_NebulaStore \
  Qoliber_NebulaSystem \
  Qoliber_NebulaUser \
  Qoliber_NebulaCurrency \
  Qoliber_NebulaReports \
  Qoliber_NebulaMedia \
  Qoliber_NebulaQuill \
  Qoliber_NebulaDirective \
  Qoliber_NebulaUiTransformer

Module order matters. The modules declare proper sequence dependencies in their module.xml files, so Magento will load them in the correct order. Qoliber_NebulaPageBuilder is intentionally disabled in RC1 pending hardening.

Run setup and compile CSS

terminal

# Run Magento setup
php bin/magento setup:upgrade
php bin/magento setup:di:compile

# Install Tailwind and compile CSS
cd app/design/adminhtml/Qoliber/Nebula/web
npm install
npm run build

# Back to Magento root
cd -

The npm run build command compiles Tailwind CSS from web/css/source/app.css to web/css/dist/app.css.

Fix the theme parent (one-time)

Magento may auto-set a parent theme during setup:upgrade. Nebula has no parent — it's a clean break. Run this SQL once:

SQL

UPDATE theme
SET parent_id = NULL
WHERE theme_path = 'Qoliber/Nebula';

Skip this if you're running MageOS with the Theme Switcher module disabled. The ForceAdminTheme plugin handles theme activation.

Deploy and flush

terminal

# Remove old static files
rm -rf pub/static/adminhtml/Qoliber

# Deploy static content (optional in dev)
php bin/magento setup:static-content:deploy -f --area adminhtml

# Flush all caches
php bin/magento cache:flush

Open your admin panel — you should see the Nebula theme.

Development Workflow

CSS Watch Mode

Start the Tailwind watcher for instant CSS updates during development:

terminal

cd app/design/adminhtml/Qoliber/Nebula/web
npm run dev

This watches all @source paths defined in app.css — templates from the theme and from app/code/Qoliber/** modules. Rebuilds in ~200ms.

Quick iteration cycle

terminal

# After editing .phtml or .xml files:
rm -rf pub/static/adminhtml/Qoliber && php bin/magento cache:flush

# After editing PHP files:
rm -rf generated/code/Qoliber && php bin/magento cache:flush

# After editing layout XML:
php bin/magento cache:clean layout block_html full_page

Project Structure

File tree

app/
├── code/Qoliber/
│   ├── Nebula/                    # Core — theme forcing, menu, config
│   ├── NebulaComponent/           # JSON engine — loader, merger, snippets
│   ├── NebulaGrid/                # Grid runtime + data providers
│   ├── NebulaForm/                # Form runtime + field renderers
│   ├── NebulaTheme/               # Catalog, sales, customer, CMS coverage
│   ├── NebulaSkin/                # 18 skin presets + runtime CSS
│   ├── NebulaMenu/                # Pinned menu items + drag-drop
│   ├── NebulaMedia/               # Media browser and image picker
│   ├── NebulaQuill/               # Rich text editor integration
│   ├── NebulaReports/             # Reporting grids
│   ├── NebulaStore/               # Stores, websites, design config
│   ├── NebulaSystem/              # System screens
│   ├── NebulaUser/                # Admin users and roles
│   ├── NebulaUiRemoval/           # Selective legacy UI Component removal
│   └── NebulaUiTransformer/       # UI Component XML -> Nebula JSON drafts
│
└── design/adminhtml/Qoliber/Nebula/
    ├── theme.xml                  # No parent theme
    ├── Magento_Backend/           # Menu, dashboard, header, login
    ├── Magento_Config/            # Config page overhaul
    ├── Magento_Theme/             # Root template, page layouts
    ├── Magento_TwoFactorAuth/     # 2FA pages
    └── web/
        ├── css/source/app.css     # Tailwind source (96 CSS vars)
        ├── css/dist/app.css       # Compiled output
        ├── js/                    # Alpine, Chart.js, SortableJS
        └── package.json           # npm build/dev scripts

Creating a Custom Skin

Create a JSON file in any module's view/adminhtml/nebula/skin/ directory. The SkinLoader auto-discovers it.

app/code/YourVendor/YourModule/view/adminhtml/nebula/skin/my-brand.json

{
    "id": "my-brand",
    "label": "My Brand",
    "colors": {
        "--color-nebula-50":  "#fef2f2",
        "--color-nebula-100": "#fee2e2",
        "--color-nebula-200": "#fecaca",
        "--color-nebula-300": "#fca5a5",
        "--color-nebula-400": "#f87171",
        "--color-nebula-500": "#ef4444",
        "--color-nebula-600": "#dc2626",
        "--color-nebula-700": "#b91c1c",
        "--color-nebula-800": "#991b1b",
        "--color-nebula-900": "#7f1d1d",
        "--color-nebula-950": "#450a0a"
    },
    "density": {
        "--nebula-font-size-base": "0.9375rem",
        "--nebula-spacing-md": "0.75rem",
        "--nebula-radius-lg": "0.5rem",
        "--nebula-sidebar-width": "15rem"
    },
    "dark": {
        "--color-nebula-500": "#f87171",
        "--color-nebula-600": "#ef4444"
    }
}

Then select your skin in Stores → Configuration → Admin → Nebula Theme → Skin.

Available skin sections

colorsNebula palette (--color-nebula-50 through 950)

densityFont sizes, spacing, radius, sidebar width

shadowsBox shadow overrides (sm, md, lg)

transitionsAnimation speed (--nebula-transition-speed)

accessibilityStatus colors for color-blind users

customAny arbitrary CSS variables

darkDark mode overrides (applied to .dark class)

Adding a Custom Grid

Create a JSON file in your module's view/adminhtml/nebula/grid/ directory.

app/code/YourVendor/YourModule/view/adminhtml/nebula/grid/custom_listing.json

{
    "id": "custom_listing",
    "title": "My Custom Grid",
    "acl": "YourVendor_YourModule::listing",
    "dataSource": {
        "provider": "YourVendor\\YourModule\\Model\\Grid\\DataProvider",
        "config": {
            "collection": "YourVendor\\YourModule\\Model\\ResourceModel\\Entity\\Collection"
        }
    },
    "settings": {
        "pageSize": 20,
        "defaultSort": { "field": "entity_id", "dir": "desc" }
    },
    "columns": {
        "entity_id": {
            "field": "entity_id",
            "label": "ID",
            "sortable": true,
            "width": "80px"
        },
        "name": {
            "field": "name",
            "label": "Name",
            "sortable": true,
            "filterable": true,
            "filter_type": "text"
        },
        "status": {
            "field": "status",
            "label": "Status",
            "@use": "snippet/status_badge",
            "options": {
                "1": { "label": "Active", "class": "success" },
                "0": { "label": "Inactive", "class": "neutral" }
            }
        },
        "actions": {
            "field": "entity_id",
            "label": "Actions",
            "type": "actions",
            "actions": {
                "edit": {
                    "label": "Edit",
                    "route": "yourmodule/entity/edit",
                    "params": { "id": "{{entity_id}}" }
                }
            }
        }
    }
}

Extending Existing Grids & Forms

Nebula's deep-merge system lets any module overlay any existing definition. Create a file with the same name in your module — it merges automatically.

app/code/YourVendor/YourModule/view/adminhtml/nebula/grid/product_listing.json

{
    "columns": {
        "custom_attribute": {
            "field": "custom_attribute",
            "label": "My Custom Column",
            "sortable": true,
            "position": 55
        },
        "sku": {
            "$remove": true
        }
    }
}

Deep merge rules: Objects merge recursively. Arrays with "$remove": true delete the key from the base definition. All arrays auto-sort by position after merging.

Admin Configuration

Go to Stores → Configuration → Admin → Nebula Theme to configure:

Menu Position

Sidebar (left) / Top (horizontal)

Default: Sidebar

Skin

15 presets + any custom skins

Default: Indigo

Per-user features (no config needed — automatic):

Dark mode toggle — stored in localStorage per browser
Sidebar collapse state — stored in localStorage
Pinned menu items — stored in admin user extra data
Pinned config sections — stored in admin user extra data

Next Steps

Explore all features See legacy vs Nebula comparison Browse 18 skin presets View module ecosystem