Get started

Get started

This page builds a working kibble in a few minutes: a panel you toggle from the top bar or a shortcut.

1. Create the files

A kibble is a folder with a package.json. Nana loads the folder’s dist/ build output when it has one, otherwise the folder itself, so a plain HTML page needs no build step.

hello/
  package.json
  panel.html

package.json:

{
  "name": "hello",
  "version": "0.1.0",
  "nana": {
    "description": "Says hello",
    "permissions": ["panels:write", "notifications:write"],
    "panels": [{ "id": "hello", "title": "Hello", "entry": "panel.html" }],
    "commands": [
      {
        "id": "toggle",
        "title": "Hello: Toggle Panel",
        "action": { "kind": "togglePanel", "panel": "hello" },
        "defaultShortcut": "ctrl+opt+h"
      }
    ],
    "topbarItems": [
      { "id": "hello", "icon": "sparkles", "command": "toggle", "tooltip": "Hello" }
    ]
  }
}

panel.html:

<!doctype html>
<body style="background: var(--nana-background); color: var(--nana-foreground)">
  <button id="hi">Say hello</button>
  <script>
    document.getElementById("hi").onclick = () =>
      nana.notifications.notify({ title: "Hello", body: "From my extension" });
  </script>
</body>

The kibble name should use lowercase letters, digits, ., and -. Its pages don’t load otherwise.

2. Load it

  1. Open Settings → Kibbles and choose Load Unpacked….
  2. Pick the hello folder.
  3. Open its entry and turn it on. Kibbles start disabled.
  4. Click the sparkles icon in the top bar, or press Ctrl+Opt+H.

The kibble shows an Unpacked badge. After editing, choose Reload. Unload folder removes it from Nana and keeps your files.

3. Use a build tool

For anything bigger, use any web tooling, such as Vite. Point every entry at paths inside your build output, and copy package.json into dist/ as part of the build. Only dist/ is published.

"scripts": {
  "build": "vite build && cp package.json dist/"
}

Debugging

  • console.log, console.warn, and console.error from pages and scripts go to the kibble’s log, along with uncaught errors.
  • The kibble’s page in Settings → Kibbles shows recent log lines, load errors, and Reveal log.
  • The log file is logs/output.log inside the kibble’s loaded folder.

Next

← OverviewManifest →