Building Custom Malet Apps

Mallnline offers two ways to run a Malet:

Malet Verticals — The no-code path. Choose your Vertical, arrange widget slots, pick a theme, and start selling. No coding required.
Malet Apps — The developer path. Build a fully custom storefront as a single-page application (SPA), and the Mallnline platform handles everything else — identity, payments, search, and security.

This guide covers the developer path.

What Is a Malet App?

A Malet App is a custom web application that runs inside your Malet on Mallnline. Instead of using the standard widget-based storefront, you write your own frontend — using any web technology you like (React, Vue, Svelte, vanilla JavaScript). Your app communicates with the platform through the @mallnline/sdk, which gives you typed access to:

Products — List, create, and update your catalog
uCart — Add items, view cart, trigger checkout
Services & Bookings — Display availability and accept reservations
Blog Posts — Publish content
uChat — Open conversations with Visitors
Media — Upload images and files
Search — Full-text search across your catalog
Payments — Create payment intents
Identity — Know who your Visitors are via uID

How It Works

You build your app using any frontend framework
You import @mallnline/sdk and initialize it with your Malet's handle
Your app is deployed to a CDN and registered in your Malet's App Manifest
When a Visitor navigates to your Malet, the platform loads your app in a secure sandbox
Your app communicates with the platform via the SDK — you never handle raw API keys

Your Visitors experience your custom design, but all the underlying commerce — uCart, Murchases, payments — is handled by the platform.

Getting Started

import { MaletApp } from '@mallnline/sdk';

const app = new MaletApp({
  maletId: 'your-malet-handle',
  version: '1.0.0',
});

// List your products
const products = await app.products.list({ first: 20 });

// Add to the Visitor's uCart
await app.cart.addItem({
  itemId: products.edges[0].node.id,
  quantity: 1,
});

// Show a notification
app.shell.showToast('Added to cart!', 'success');

Scopes & Permissions

When you register your Malet App, you declare which platform features it needs access to. These are called scopes. For example:

Scope	What it lets your app do
`read:products`	List and view products
`write:cart`	Add items to the Visitor's uCart
`read:profile`	See who the Visitor is (public profile only)
`send:uchat`	Send messages in uChat

Your app can only access features matching its declared scopes. If you request a feature your app hasn't declared, the platform will block the request — this keeps Visitors safe and builds trust.

Security & Sandboxing

Your Malet App runs in a sandboxed environment:

Isolated — Your code runs in its own browser context, completely separate from the main Mallnline page and other Malets
No raw tokens — Your app never holds API keys or auth tokens. All communication goes through the secure SDK bridge
Rate limited — API calls are capped to prevent abuse
Scope-checked — Every SDK call is validated against your declared permissions

TIP

This is similar to how apps work on your phone — each app asks for specific permissions, runs in its own sandbox, and communicates with the OS through a controlled API.

App Lifecycle

Your Malet App goes through a review process before going live:

Draft — You're building and testing locally
In Review — You've submitted your app for platform review
Approved → Published — Your app is live at /@your-handle
Rejected — The review found issues; fix them and resubmit

NOTE

The review process checks for security issues, performance, and compliance with the Mallnline Terms of Service. Think of it like the App Store review — it's there to protect Visitors.

Theming & Platform Chrome

Your Malet App can read the current theme and integrate with the platform's UI:

// Get your Malet's theme tokens
const theme = await app.shell.getTheme();
document.body.style.setProperty('--primary', theme.primaryColor);

// Set the page title (appears in the platform's nav bar)
app.shell.setTitle('My Custom Page');

// Navigate within the platform
app.shell.navigate('/checkout');

Real-Time Events

Subscribe to platform events to keep your UI in sync:

app.events.on('murchase.paid', (data) => {
  // A Visitor just completed a purchase!
  console.log('New Murchase:', data);
});

Frequently Asked Questions

Can I use any frontend framework? Yes — React, Vue, Svelte, Angular, or vanilla HTML/CSS/JS. The SDK is framework-agnostic. As long as your app runs in a browser, it works with @mallnline/sdk.

Do I need to handle payments myself? No. When you call app.cart.checkout(), the platform handles the entire checkout flow — payment processing, Murchase creation, and receipt generation. You never see credit card numbers.

How do I test my app locally? Use npm run dev with your local dev server. The SDK includes a mock bridge for local development that simulates platform responses.

Can Visitors still use uCart and uChat on my custom Malet? Absolutely. Your Malet App runs inside the platform shell, so uCart, uChat, and all platform features remain available. Your app just controls the visual experience.

What happens to my existing Malet if I switch to a Malet App? Your existing Vertical-based storefront is preserved. You can switch between Track 1 (Verticals) and Track 2 (App) at any time — both are saved.

Is there a size limit for my app? Yes — your App Manifest declares resource limits including maximum bundle size. The default is generous enough for a full SPA. If you need more, contact the platform team.