# 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`:

```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`:

```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.

```json
"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

- Declare what it does in the [manifest](https://nana.areshk.dev/docs/extensions/manifest.md).
- Ask for the minimum [permissions](https://nana.areshk.dev/docs/extensions/permissions.md).
- Add [tabs](https://nana.areshk.dev/docs/extensions/tabs.md), [panels](https://nana.areshk.dev/docs/extensions/panels.md), [bar items](https://nana.areshk.dev/docs/extensions/bar-items.md), and
  [commands](https://nana.areshk.dev/docs/extensions/commands.md).
- Work with [files](https://nana.areshk.dev/docs/extensions/files.md), [Git](https://nana.areshk.dev/docs/extensions/git.md), and [events](https://nana.areshk.dev/docs/extensions/events.md).
- [Publish it](https://nana.areshk.dev/docs/extensions/contributing.md).