NNuvaka General AppDeveloper docs
TRDownload

Nuvaka › Developer docs › Home widgets

Home page widgets

Every user designs their own Nuvaka home page with drag and drop. Your extension can offer one or more widgets for it: a small view that runs in its own box, such as rates, weather, a timer or a to-do list. The layout is stored in the account and looks the same on all of the user's devices.

Note: App support arrives with Nuvaka 0.3.1. An extension that offers widgets should use "minAppVersion": "0.3.1".

Manifest: contributes → home.widget

"entry": { "ui": "index.html" },
"pages": [
  { "id": "main", "title": { "tr": "Kurlar", "en": "Rates" } },
  { "id": "ticker", "title": { "tr": "Kur widget'ı", "en": "Rates widget" } }
],
"contributes": {
  "home.widget": [
    { "id": "ticker", "title": { "tr": "Kur", "en": "Rates" }, "page": "ticker",
      "sizes": [{ "w": 2, "h": 1 }, { "w": 4, "h": 2 }], "minRefreshSec": 300, "configurable": true, "icon": "chart-line" }
  ]
}
FieldRule
idrequired; [a-z0-9-]{1,30}, unique within the extension
titlerequired; { tr, en? }
pagerequired; the page the widget opens, must be in pages
sizes1–6 sizes, each { w: 1–4, h: 1–4 } (grid units). The user can only pick one of these.
minRefreshSecoptional; 60–86400. Without it the widget is not refreshed automatically.
configurableoptional; when true the widget gets a "Configure" option on the home page.
iconoptional icon name
  • At most 5 widgets per extension.
  • Widgets do not send every version to review. Per-version review applies only to the storage.* points that touch My Files (Review rules).
  • The install screen's permission list shows a "Home page widget" row.
  • Store cards and details return widgets: [{ id, title, sizes }] (null if none); GET store?hasWidgets=true lists only extensions with widgets.

How a widget runs

  • A widget is your extension's page opened in a small frame. Sandbox, CSP and permissions are the same as the normal page; it gets no extra rights.
  • Your page knows it is a widget from nuvaka.ui.presentation(), which returns 'widget'. In this mode hide your own menu and header and draw only a summary that fits the box.
  • A widget draws only inside its own box. A click opens the extension's main page.
  • When the home page is hidden the widget is paused (the frame is kept). It never refreshes more often than minRefreshSec.
  • Widget frames don't count toward the open-app limit (apps.keepAliveMax); the home page has its own limit (e.g. 12 live widgets, the rest "click to load").
  • The SDK namespace nuvaka.ui.widget (size, config, resize events) arrives with 0.3.1; its signature will be added to the API reference when released. Until then use the frame's own size (window.innerWidth/innerHeight, the resize event).

Layout (for reference)

The user edits the layout; extensions cannot read or change it. The app stores the layout in the account (GET/PUT /api/home/layout, MVCC) and changes reach all devices immediately. A widget is stored in the layout as ext:<extension id>/<widget id>. If the extension is uninstalled the widget stays in the layout, shown as "app removed", and comes back when the extension is reinstalled.

Nuvaka Apps API v1 · last updated 2026-09-28