Skip to content

Nebula UI Bridge

UI Bridge converts supported Magento UI Component grids and forms into Nebula screens at runtime. It helps adapt third-party admin modules without first rewriting every screen as a Nebula JSON definition.

The 1.0.0 package is nebula/module-ui-bridge, maintained in nebula/ui-bridge. It is included in nebula/admin and distributed under the Nebula Community License.

Included, with runtime conversion disabled by default

A normal Nebula Admin installation already installs UI Bridge. Enable its configuration flag when you are ready to test the third-party screens on your staging store. It does not provide a Knockout or RequireJS runtime, and it cannot convert every custom component.

Install and enable

Follow the Nebula installation guide, including the free checkout and Composer authentication. You do not need a separate Composer require command for UI Bridge when installing nebula/admin.

Enable runtime conversion:

bin/magento config:set nebula/ui_bridge/enabled 1
bin/magento cache:clean config layout block_html nebula_ui_bridge
Config path Default Meaning
nebula/ui_bridge/enabled 0 Enables conversion when Nebula is rendering the admin.
nebula/ui_bridge/skip_canonical 0 Debugging option: attempts runtime conversion even when a hand-written Nebula definition exists. Leave it off for normal use.

UI Bridge 1.0.0 requires the Nebula Component, Core, Form, Grid and Theme modules. Its manifest targets magento/framework ~103.0.9 and PHP 8.3, 8.4 or 8.5. The store's supported PHP version also depends on the platform; see Requirements.

How it works

  1. The layout reader encounters a named Magento <uiComponent>.
  2. The shared Nebula definition resolver first looks for a canonical grid or form definition, including supported name variants.
  3. If no canonical definition exists, the bridge reads the source XML and checks the component's declared ACL resources.
  4. It prepares the UI Component with data-provider queries suppressed, extracts its configuration, and passes it through the converter registry.
  5. The layout entry becomes a Nebula grid or form block using the resolved definition identifier.

The page, data, export and action endpoints use the same definition resolver. A component without declared ACL resources is rejected. Unsupported fields and components produce a conversion failure rather than a form that silently omits them.

Prepared definitions contain user, locale, URL and entity data. They are memoized only within the current request. Old shared cache and generated-file payloads are ignored, and Magento's layout cache retains the definition identifier. You do not need to remove old generated definition files to enable conversion.

Source: Plugin/UiComponentDispatcher.php, Plugin/ResolveDefinition.php, Model/RuntimeDefinitionResolver.php and etc/di.xml in the UI Bridge repository.

Grids and data providers

Converted listings use the registered provider bridge.grid.collection. Its bridge-specific collection registry handles the collection classes discovered in the source UI configuration. This is separate from the ordinary grid.collection provider, which expects a registered alias.

Column renderers cover common text, boolean, select, date, thumbnail, link and action columns. Magento column classes with computed values can be rendered through prepareDataSource(). Custom HTML output remains escaped unless the column class is explicitly registered as returning trusted markup.

Search applies to source columns declared as text with a text filter. Columns computed by a Magento column class are not searchable through that mechanism. A leading-wildcard search can be expensive on large tables; use a canonical Nebula definition when you need a different search strategy.

Forms and validation

The bridge maps supported form fields and validation rules onto Nebula's form engine. The supported validation rules are required, number, min, max, minLength, maxLength, email and pattern.

Unsupported Magento validation rules are dropped with a warning. Review the source module's save controller and validation requirements before enabling its forms in production. A custom rule or field may need a dedicated converter or a canonical Nebula form.

Extending it

Custom presentation

Register your renderer in the global etc/di.xml:

<type name="Nebula\Component\Model\RendererPool">
    <arguments>
        <argument name="columnRenderers" xsi:type="array">
            <item name="my_type" xsi:type="object">Vendor\Module\Renderer\MyColumnRenderer</item>
        </argument>
    </arguments>
</type>

The renderer implements Nebula\Component\Api\V1\ColumnRendererInterface. Keep registry contributions in the global etc/di.xml; an area-specific argument can replace the merged registry for that area.

Custom component conversion

Implement Nebula\UiBridge\Api\NodeConverterInterface and contribute it to the converter registry in global DI. The interface exposes supports(NodeContext $node) and convert(NodeContext $node, ConverterContext $ctx): NodeResult.

Use the UI Bridge package documentation for converter and computed-column integration details, and Extension points for the Nebula renderer and data-provider registries.

The offline alternative

Nebula_UiTransformer is a separate module included with nebula/admin. It is not bundled inside the UI Bridge package.

bin/magento nebula:ui:transform vendor/magento/module-cms

The command writes draft Nebula JSON and layout stubs for review and completion in your own module. Use it when you want to own the definitions in version control. See Generators and the CLI reference.

Status and known compatibility issues

These instructions describe UI Bridge 1.0.0. Older instructions for qoliber/nebula-ui-bridge 0.9.0, duplicated transformer registrations, inline-only definitions and shared prepared-definition caches do not describe the current package.

Compatibility still depends on the source component. Test every extension screen you enable:

  • Confirm its rows and fields appear, including any changes to core screens.
  • Exercise filters, search, paging, export and primary actions.
  • Check that forms save the intended fields and reject invalid input.
  • Test an administrator with restricted permissions.
  • Review the browser console and Magento logs for unsupported components or dropped validation rules.

For a component the bridge cannot convert, provide a canonical Nebula definition or add a converter. See Third-party extensions for the wider compatibility checklist.

Privacy policy Nebula Community License