Litium Developer

Litium Developer

Overview

Partner developers building on Litium platform use this skill for implementation guidance. This skill delegates to the litium-cloud-cli sub-skill for cloud deployment. For all other Litium topics — including React Accelerator, MVC, data modelling, and APIs — it loads reference files on demand.

Always read references/partner-guidance.md first before helping modify Litium platform files.

Delegation

For this area, delegate entirely to the named skill — do not duplicate its content here:

Reference map

Read these files only when the user's task requires that area:

Documentation search priority

1. Primary: https://docs.litium.dev/ — always try first for official docs.
2. Community: https://forum.litium.com/ — for real-world solutions; load references/forum-api.md to search programmatically.

Quick-start routing

Step 0 (always): Read references/partner-guidance.md first to understand what partners can/cannot modify.

• "How do I work on the React storefront?" → read references/react-accelerator/overview.md first, then load specific references as needed (template-routing, code-patterns, etc.).
• "How do I deploy/manage Litium Cloud environments?" → delegate to litium-cloud-cli.
• "How do I set up Litium locally?" → load the matching setup reference (empty / MVC / React).
• "How do I add cart or wishlist functionality?" → load references/cart-and-wishlist.md.
• "How do I create a custom field type or field template?" → load references/data-modelling.md.
• "How do I call the Admin Web API or a Connect API?" → load references/apis.md.
• "How do I build a backoffice UI extension?" → read references/extension/cli-commands.md first, then load specific references as needed (framework-patterns, bridge-api, routing, etc.).
• "How do I add a panel or settings page to an extension?" → load references/extension/cli-commands.md (always use the CLI — never create files manually).
• "How do I navigate or show notifications in an extension?" → load references/extension/bridge-api.md.

Backoffice UI Extension Architecture

Extensions are Web Components (Custom Elements) loaded as IIFE bundles. They run in complete isolation from the Angular 20 admin host — React, Vue, Angular, or Vanilla JavaScript all work. The host communicates with extensions exclusively through window.litiumExtension.

┌───────────────────────────────────────────────────────────┐
│  Litium Admin (Angular 20 host)                           │
│                                                           │
│  ┌─────────────────────────────┐                         │
│  │  <litium-ext-my-widget>     │  ← Custom Element       │
│  │                             │    (your extension)     │
│  │  ┌─────────────────────┐   │                         │
│  │  │   Your framework    │   │                         │
│  │  │   (React / Vue /    │   │                         │
│  │  │    Angular / Vanilla│   │                         │
│  │  └─────────────────────┘   │                         │
│  │            │               │                         │
│  │            ▼               │                         │
│  │  window.litiumExtension     │  ← Bridge API           │
│  └─────────────────────────────┘                         │
│              │                                            │
│  navigate() · showNotification() · getContext()           │
│  on('routeChanged') · on('contextChanged') · off()        │
└───────────────────────────────────────────────────────────┘

Extension Critical Rules

These rules MUST be followed in every extension. Violating them causes runtime failures.

Always Use the CLI — Never Create Files Manually

When scaffolding a new project, adding a panel, or adding a settings page, MUST use the @litiumab/platform-extension-sdk CLI (see references/extension/cli-commands.md). Do NOT manually create component files, manifest entries, or index imports — the CLI handles all three correctly.

Only write code manually inside the generated component files (implementing the UI logic).

Custom Element Tag Naming

• All tags MUST start with litium-ext-
• Pattern: litium-ext-{extension-id} for the main element
• Panels: litium-ext-{extension-id}-panel-{slug}
• Must match regex: /^litium-ext-[a-z][a-z0-9-]*$/

Guard customElements.define

if (!customElements.get('litium-ext-my-extension')) {
  customElements.define('litium-ext-my-extension', MyElement);
}

Cleanup Event Subscriptions

Always unsubscribe from window.litiumExtension.on() in disconnectedCallback / onUnmounted / ngOnDestroy. Failing to do so causes memory leaks.

Never Call navigate() Inside a routeChanged Handler

Creates an infinite loop. Only call navigate() in response to user actions.

Use Memory-Based Routing

Extensions must NOT call history.pushState directly. Use MemoryRouter (React), createMemoryHistory (Vue), or MemoryLocationStrategy (Angular).

NPM Registry Configuration

# .npmrc
@litiumab:registry=https://registry.npmjs.org/

Extension Quick Workflows

Creating a New Extension

1. Read references/extension/cli-commands.md
2. Ask the user which framework: react, vue, angular, or vanilla
3. Run: npx @litiumab/platform-extension-sdk create <name> --framework <framework>
4. cd <name> && npm install
5. Read references/extension/framework-patterns.md for the chosen framework
6. Start dev server: npm run dev
7. Register in Litium via Settings > Extensions (see references/extension/deployment.md)

Adding a Panel / Settings Page

1. Read references/extension/cli-commands.md
2. From the extension project root, run npx @litiumab/platform-extension-sdk add panel or add settings-page
3. The CLI generates the component file, updates the manifest, and injects the import
4. For settings pages: add the route in the framework router (see references/extension/routing.md)

Building and Deploying

1. Read references/extension/deployment.md
2. npm run build — produces dist/extension.js
3. Upload to a CDN or hosting server (HTTPS required for production)
4. Update bundleUrl in extension.manifest.json
5. Install via Settings > Extensions or POST to the Extension Management API

Extension Common Mistakes