> ## Documentation Index
> Fetch the complete documentation index at: https://docsv4.mile.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Publishing an Add-on

> Build the add-on file, upload and publish it in Settings › Add-ons, update it later and fix common problems.

## Build and check the file

```bash theme={null}
pnpm build
```

Before uploading, check three things:

| Check | Command | Expected |
| - | - | - |
| One file | `ls dist/static/js/` | exactly one `.js` file |
| React not included | `grep -c __SECRET_INTERNALS dist/static/js/*.js` | `0` |
| Uses the app's libraries | `head -c 300 dist/static/js/*.js` | mentions `React` and `MileUI` |

## Upload the add-on

Open **Settings › Add-ons** and click **New**.

> [!NOTE]
>
> **New** is shown to organizations that build add-ons, to users with the Create Add-on permission. See [Add-ons](https://docsv4.mile.app/pages/add-ons/introduction.md#publish-your-own-add-on).

| Field | What to enter |
| - | - |
| **Name** | Shown on the add-on card |
| **Description** | One sentence on what it does |
| **Organization ID** | Your own organization's ID while testing. **Left empty, the add-on goes to the catalogue of every organization** |
| **Plugin bundle** | Your file from `dist/static/js/` |
| **Icon** | Optional square image for the card |

Click **Save**. The add-on is saved **unpublished**. Click **Publish** on its card to show it in the catalogue, and use **Preview as customer** to check what other organizations see.

## Add it and open it

1. On the add-on's card, click **Add**, check the name and address, and save.
2. The add-on appears in the left menu straight away.
3. Open it. If it has a one-time setup, finish it.
4. Give the add-on's permissions to other roles in [Permission](https://docsv4.mile.app/pages/settings/permission/introduction.md).

Then sign in with a user who has a smaller role and check every page again.

## Update the add-on

Build a new file, click **Edit** on the card, choose the new file and save. The old file is replaced; the add-on's settings and permissions stay. Users get the new version next time they open it.

> [!WARNING]
>
> There is no version history. Keep your previous file, and tag the code you built it from, in case you need to go back.

## Unpublish or delete

* **Unpublish** takes it out of the catalogue. Organizations that already added it keep it.
* **Delete** removes it for every organization and cannot be undone.

## Troubleshooting

| What you see | What to do |
| - | - |
| "This module could not be loaded" | The build made more than one file, or `src/plugin-entry.ts` does not export `definePlugin(...)`. Rebuild and check |
| Blank page or "Invalid hook call" | React was packed into your file. Undo changes to the build settings |
| The add-on has no styles | Keep `import './styles.css'` in `src/plugin-entry.ts` |
| Not in the left menu after adding | Reload the page once |
| Settings or saved data disappeared after renaming the add-on | Rename it back. Settings are stored under the add-on's name |
| The preview says "not signed in" | Check `.env`: the API address ends with `/`, both addresses are the same environment, and the token is from that environment |
| The add-on is missing from the catalogue | Publish it. A file that doesn't declare pages with `definePlugin` is not shown |
| Works in the preview, fails after upload with a network error | The page calls a server outside MileApp. Use a webhook automation instead |
| After setup, users still see "no access" | Grant the add-on's permissions to their role in [Permission](https://docsv4.mile.app/pages/settings/permission/introduction.md) |
| The preview shows "ReactDOM is not defined" | Stop and restart `pnpm dev` |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.