Facade

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
fe_facade_url	no	https://web-host.wippy.ai/webcomponents-1.0.21	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
hide_session_selector	false	세션 선택 UI 숨김

Theming

세 가지 범위가 적용됩니다: global(모든 곳), host(iframe 주변 chrome), children(iframe 내부 콘텐츠).

Parameter	범위	Default	Description
custom_css	global	Google Fonts import	모든 범위에 주입되는 CSS
css_variables	global	{}	CSS 커스텀 프로퍼티의 JSON 맵
icon_sets	global	[]	Iconify 아이콘 세트 URL
host_custom_css	host	""	호스트 chrome 전용 CSS
host_css_variables	host	{}	호스트 전용 CSS 커스텀 프로퍼티
host_icon_sets	host	[]	호스트 전용 아이콘 세트
children_custom_css	children	""	iframe 콘텐츠 전용 CSS
children_css_variables	children	{}	iframe 콘텐츠 전용 CSS 커스텀 프로퍼티
login_path	—	/login.html	인증되지 않은 사용자의 리다이렉트 경로

선택적 hostConfig JSON

다음 파라미터는 각각 JSON으로 인코딩된 문자열이며 기본값은 비어 있습니다({} 또는 []). hostConfig 아래에서 프런트엔드로 그대로 전달됩니다.

Parameter	Default	Description
api_routes	{}	프런트엔드 라우트 오버라이드
additional_nav_items	[]	추가 사이드바 항목
state_cache	{}	프런트엔드 상태 캐시 구성
allow_additional_tags	[]	채팅에서 추가로 허용할 HTML 태그
chat	{}	채팅 UI 오버라이드
axios_defaults	{}	프런트엔드 axios HTTP 클라이언트 기본값

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",
    "login_path": "/login.html",
    "env": {
        "APP_API_URL": "https://api.example.com",
        "APP_AUTH_API_URL": "https://api.example.com",
        "APP_WEBSOCKET_URL": "wss://api.example.com"
    },
    "routePrefix": "https://api.example.com",
    "axiosDefaults": { "...": "..." },
    "theming": {
        "global":  { "customCSS": "...", "cssVariables": {}, "iconSets": {} },
        "host":    { "customCSS": "...", "cssVariables": {}, "iconSets": {}, "i18n": { "app": { "title": "Wippy", "icon": "wippy:logo", "appName": "Wippy AI" } } },
        "children": { "customCSS": "...", "cssVariables": {} }
    },
    "hostConfig": {
        "session": { "type": "non-persistent" },
        "history": "hash",
        "showAdmin": true,
        "allowSelectModel": false,
        "startNavOpen": false,
        "hideNavBar": false,
        "disableRightPanel": false,
        "hideSessionSelector": false,
        "apiRoutes":         { "...": "..." },
        "additionalNavItems": [],
        "stateCache":        { "...": "..." },
        "allowAdditionalTags": [],
        "chat":              { "...": "..." }
    }
}

API URL은 PUBLIC_API_URL 환경 변수에서 읽어옵니다. APP_WEBSOCKET_URL은 http://를 ws://로 또는 https://를 wss://로 대체하여 파생됩니다. 테마는 세 가지 범위(global, host, children)를 가지며 — host.i18n은 앱 브랜딩을 담습니다. hostConfig 키는 camelCase이며 facade 파라미터에서 조립됩니다: session_type, history_mode, show_admin, allow_select_model, start_nav_open, hide_nav_bar, disable_right_panel, hide_session_selector, 그리고 선택적 api_routes, additional_nav_items, state_cache, allow_additional_tags, chat, axios_defaults.

Navigation Sidebar

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/

Sidebar Groups

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.

See Also

• Views - Page and component system
• HTTP Server - HTTP service configuration
• Framework Overview - Framework module usage