Kibbles Overview
New here? Start with Get started.
A kibble is a web project that adds to the desktop app: tabs, panels, popovers, a sidebar, top bar and status bar items, palette commands, shortcuts, background logic, and app languages. You build it with any web tooling and Nana loads the build output.
Kibbles are Nana’s extensions. The API, manifest, and folders still use the
word extension, for example nana.extensionID and extension. events.
Where code runs
| Where | What it is | API |
|---|---|---|
| Pages | Tabs, panels, popovers, the sidebar, and modal web views. The system’s own engine, WebView2, in a native host over the app, alive while hidden. |
window.nana, async (Promises) |
| Scripts | A runScript command. Runs once in QuickJS on its own thread. |
nana, synchronous |
| Background | The optional background script. Runs while the kibble is enabled. Receives events. |
nana, synchronous |
Not every API exists everywhere. See the API reference.
File, Git, and exec work runs on the project’s server, so it works the same
for local and remote projects. Web requests run in the desktop app.
Pages
| Page | What’s in it |
|---|---|
| Get started | Build, load, and debug a kibble |
| Manifest | package.json fields |
| Permissions | Permissions and runtime prompts |
| API reference | Every nana namespace and where it is available |
| Events | Workspace events and kibble messages |
| Tabs | Tab types, file openers, page data, and theme |
| Panels | Panels, popovers, and the sidebar |
| Bar items | Top bar and status bar items |
| Commands | Palette commands, shortcuts, and scripts |
| Dialogs | Dialogs, pickers, and modal web views |
| Files | Reading and writing project files |
| Git | Repository, branches, pull requests, and worktrees |
| Localizations | Language packs |
| Contributing | Publish to the marketplace |
Where kibbles live
Installed kibbles live in the extensions/<name>/ folder of Nana’s
profile folder. Each is the build output, with
package.json at its root.
Manage them in Settings → Kibbles: Installed lists them with their permissions, settings, and logs; Browse installs from the marketplace. Kibbles start disabled after installing or loading.
Security
- Declared permissions. Most API calls need a permission in the manifest. Web requests, dialogs, and events need none.
- Runtime prompts. Running programs, typing into terminals, writing files or Git, web requests, and deleting projects ask the user first.
- Declared events. A kibble only receives the workspace events it lists in its manifest.
- Own files only. Pages load only from the kibble’s own folder.
- Verified installs. Marketplace packages are checked against their listing before they are installed.