> For the complete documentation index, see [llms.txt](https://docs.iynxdev.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.iynxdev.com/addon-api/getting-started/custom-dashboard-pages.md).

# Custom Dashboard Pages

This page explains how plugins can ship custom dashboard pages.

***

## 1. How loading works

When Athena starts and the dashboard is enabled, it checks every loaded plugin for:

* `/plugins/<plugin_name>/src/dashboard/addon.json`

If present, Athena copies your plugin dashboard files into the main dashboard app and adds your addon to the sidebar automatically.

***

## 2. Required manifest

Create:

* `/plugins/<plugin_name>/src/dashboard/addon.json`

Example:

```json
{
  "name": "Template Addon",
  "slug": "template-addon",
  "icon": "TbPlug",
  "description": "Sample custom dashboard page bundled with the plugin template."
}
```

### Required fields

* **name:** Sidebar or page title.
* **slug:** URL path key. It must be unique.

### Optional fields

* **icon:** Tabler icon key. Defaults to `TbPlug`.
* **description:** Subtitle shown in the addon layout header.

> The `slug` should be lowercase kebab-case and should not change after release, otherwise old links and bookmarks may break.

***

## 3. Folder structure

Use this structure inside your plugin:

```
src/dashboard/
  addon.json
  pages/
    page.jsx
  components/
    HelloCard.jsx
  api/
    ping/
      route.js
```

How each folder is used:

* `pages/`: Copied to the dashboard app route `/addons/<slug>/...`
* `components/`: Copied to `dashboard/components/addons/<slug>/...`
* `api/`: Copied to `dashboard/app/api/addons/<slug>/...`

***

## 4. Route and imports

For addon slug `template-addon`:

* `src/dashboard/pages/page.jsx` becomes `/addons/template-addon`
* Import shared components from `dashboard/components/addons/template-addon`

Example import in your `page.jsx`:

```js
import HelloCard from '../../../../components/addons/template-addon/HelloCard';
```

If you rename the `slug`, update any imports that include the old slug path.

The dashboard currently maps addon icons using a fixed icon map. If you use a custom icon key that is not available there, the UI falls back to `TbPlug`.

***

## 5. Fetching plugin data

The most common pattern is reading your plugin config through Web API dashboard routes:

```js
const API_BASE = process.env.NEXT_PUBLIC_ATHENA_WEB_API_URL;
const API_KEY = process.env.NEXT_PUBLIC_ATHENA_WEB_API_KEY;

const response = await fetch(`${API_BASE}/api/dashboard/config/hello/data`, {
  headers: { authorization: API_KEY }
});
```

Save updates with:

```js
await fetch(`${API_BASE}/api/dashboard/config/hello/save`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json', authorization: API_KEY },
  body: JSON.stringify({ data: updatedConfig })
});
```