Facade

The wippy/facade module provides a portable iframe facade that loads and configures the Wippy frontend from a CDN. It serves an HTML shell that creates an iframe pointing to the frontend bundle, handles authentication, and bridges configuration between the backend and frontend.

Setup

Add the module to your project:

wippy add wippy/facade
wippy install

Declare the dependency:

version: "1.0"
namespace: app

entries:
  - name: gateway
    kind: http.service
    addr: :8090
    lifecycle:
      auto_start: true

  - name: api
    kind: http.router
    meta:
      server: app:gateway
    prefix: /api/public

  - name: dep.facade
    kind: ns.dependency
    component: wippy/facade
    version: "*"
    parameters:
      - name: server
        value: app:gateway
      - name: router
        value: app:api

Configuration Parameters

Parameter	Required	Default	Description
`server`	yes	—	HTTP server for static and iframe serving
`router`	yes	—	Public API router for config endpoint
`api_url_env`	no	`PUBLIC_API_URL`	Environment variable containing the public API URL
`fe_facade_url`	no	CDN URL	Base URL for iframe frontend bundle
`fe_entry_path`	no	`/iframe.html`	Iframe HTML entry point path

App Identity

Parameter	Default	Description
`app_title`	`Wippy`	Title shown in sidebar
`app_name`	`Wippy AI`	Full application name
`app_icon`	`wippy:logo`	Iconify icon reference

Feature Flags

Parameter	Default	Description
`hide_nav_bar`	`false`	Hide the left navigation sidebar
`disable_right_panel`	`false`	Disable the right sidebar panel
`start_nav_open`	`false`	Navigation drawer open by default
`show_admin`	`true`	Show admin panel toggle
`allow_select_model`	`false`	Allow user to select LLM model
`session_type`	`non-persistent`	Chat session persistence: `non-persistent` or `persistent`
`history_mode`	`hash`	Browser history mode: `hash` or `history`

Theming

Parameter	Default	Description
`custom_css`	Google Fonts import	Custom CSS injected into iframe
`login_path`	`/login.html`	Redirect path for unauthenticated users

Config Endpoint

The facade registers GET /facade/config on the configured router. The frontend fetches this on load:

{
    "facade_url": "https://web-host.wippy.ai/webcomponents-...",
    "iframe_origin": "https://web-host.wippy.ai",
    "iframe_url": "https://web-host.wippy.ai/webcomponents-.../iframe.html?waitForCustomConfig",
    "api_url": "https://api.example.com",
    "ws_url": "wss://api.example.com",
    "feature": {
        "session_type": "non-persistent",
        "hide_nav_bar": false,
        "disable_right_panel": false,
        "show_admin": true,
        "start_nav_open": false,
        "allow_select_model": false
    },
    "customization": {
        "custom_css": "...",
        "i18n": { "app": { "title": "Wippy", "icon": "wippy:logo", "appName": "Wippy AI" } }
    },
    "login_path": "/login.html"
}

The api_url is resolved from the environment variable specified by api_url_env. The ws_url is derived by replacing https:// with wss://.

Pages registered via wippy/views appear in the sidebar automatically based on their metadata:

entries:
  - name: dashboard
    kind: registry.entry
    meta:
      type: view.page
      name: dashboard
      title: Dashboard
      icon: tabler:chart-bar
      group: Analytics
      group_icon: tabler:chart-dots
      group_order: 10
      order: 1
      announced: true
      secure: true
      url: https://cdn.example.com/dashboard/

Pages with the same group value are collected into collapsible sections. Groups are sorted by group_order (lower first), pages within groups by order.

Field	Description
`group`	Category name displayed in sidebar
`group_icon`	Icon for the category header
`group_order`	Sort position of the group (lower = higher)
`group_placement`	`"sidebar"` (in sidebar) or `"default"` (main area only)

Pages without a group appear as top-level items.

Controlling Visibility

Field	Effect
`announced: true`	Page appears in sidebar navigation
`announced: false`	Page hidden from navigation but still accessible via URL
`inline: true`	Internal page, hidden from all UI listings
`hide_nav_bar: true`	Facade parameter — hides the entire left sidebar

Publishing with Embedded Assets

When publishing a component that includes static files (like the facade's public/ directory), use --embed to include fs.directory entries in the package:

wippy publish --embed facade:public_files

Without --embed, fs.directory entries are excluded from the published package. The --embed flag accepts entry IDs or names matching fs.directory entries.