Manifest

The manifest is the package.json at the root of the extension. name and version sit at the top level; everything Nana-specific sits under nana.

{
  "$schema": "https://raw.githubusercontent.com/Areshkew/nana/main/docs/extensions/schema/manifest.schema.json",
  "name": "hello",
  "version": "0.1.0",
  "scripts": { "build": "vite build && cp package.json dist/" },
  "nana": {
    "description": "Says hello",
    "permissions": ["notifications:write"],
    "commands": [{ "id": "ping", "title": "Hello: Ping" }]
  }
}

The JSON schema gives editor completion when $schema sits at the top level. In VS Code it replaces the built-in package.json schema for that file. The schema checks publishable packages, so it also requires scripts.build. Nana ignores $schema and other keys it doesn’t know.

Loading

Nana reads dist/package.json when it exists, otherwise package.json.
Every path in the manifest (entry, background, script, icons) is relative to dist/ when the folder has one, otherwise to the folder itself. Paths can’t leave that folder.
An invalid manifest shows as a load error in Settings → Kibbles.

Top-level fields

Field	Required	Notes
`name`	yes	The kibble ID. Use `a-z`, `0-9`, `.`, and `-`; pages don’t load for other names. Must match its folder name when published or installed.
`version`	yes	Semver. Bump it for every published change.
`scripts.build`	to publish	Must leave `package.json` in `dist/`.

`nana` fields

The nana object is required; its fields are optional.

Field	Type	See
`description`	string	One line, shown in Settings.
`permissions`	string[]	Permissions
`events`	string[]	Workspace events it may receive. Events
`background`	string	Path to a script that runs while the kibble is enabled. Events
`commands`	object[]	Commands
`tabTypes`	object[]	Tabs
`fileOpeners`	object[]	Tabs
`panels`	object[]	Panels
`popovers`	object[]	Panels
`sidebar`	object	Panels
`topbarItems`	object[]	Bar items
`statusBarItems`	object[]	Bar items
`localizations`	object[]	Localizations
`settings`	object[]	Settings below
`marketplace`	object	Listing details. Contributing

IDs must be unique within their list, and every reference (a command’s panel, an item’s command) must exist.

Icons

Panels, the sidebar, and bar items take an icon:

{ "icon": "sparkles" }
{ "icon": { "symbol": "sparkles" } }
{ "icon": { "svg": "assets/icon.svg" } }

symbol is an SF Symbol name. Windows has no SF Symbols: it draws the common ones from its own icons and the kibble icon in place of the rest.
svg is a file of up to 256 KiB. It is tinted like the app’s own icons, so use currentColor or one solid color.

Settings

Declared settings appear on the kibble’s page in Settings → Kibbles.

"settings": [
  { "key": "greeting", "title": "Greeting", "type": "string", "defaultValue": "Hello" },
  { "key": "loud", "title": "Shout", "type": "bool" }
]