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

# Getting Started

> Set up the add-ons SDK, preview the starter page against your own data and produce your first add-on file.

This page takes you from nothing to a working local preview and a built add-on file, in about ten minutes.

## Before you start

| You need | Notes |
| - | - |
| Node.js | 20.19 or newer |
| pnpm | 10 or newer. Run `corepack enable` once and the right version is used |
| Git | To clone the SDK |
| SDK access | `https://repo.mile.app/mile-v4/mile-v4-ui-plugin-sdk`. Ask MileApp for access |
| Personal access token | From your MileApp account: **Profile › Personal Token** |

## Step 1: Get the SDK

Each add-on lives on its own branch, always started from `main`.

```bash theme={null}
git clone https://repo.mile.app/mile-v4/mile-v4-ui-plugin-sdk.git
cd mile-v4-ui-plugin-sdk
git checkout main
git checkout -b add-on/delivery-summary
pnpm install
cp .env.example .env
```

> [!WARNING]
>
> Build one add-on per branch, and never start a branch from an example add-on's branch. You would carry its pages and libraries into yours.

## Step 2: Name your add-on file

Open `rsbuild.config.ts` and change one line near the top:

```ts theme={null}
const globalName = 'delivery_summary';
```

This becomes the name of the file you upload. Use lowercase letters and underscores, and keep it unique in your organization.

## Step 3: Connect the preview to your account

Edit `.env`:

| Setting | Value |
| - | - |
| `PUBLIC_API_ROUTE_V3` | `https://apiwebsandbox.mile.app/` (keep the slash at the end) |
| `PUBLIC_DEV_TOKEN` | your personal access token, from an account on the same environment |
| `PUBLIC_HOST_GLOBALS_URL` | `https://v4websandbox.mile.app/host-globals.js` |

Your add-on saves real settings and permissions, so build against **sandbox**. To try it against production, use `https://apiweb.mile.app/` and `https://v4web.mile.app/host-globals.js` with a production token. Always change both addresses together.

> [!NOTE]
>
> Replace the API address that comes in `.env.example`. It no longer answers, and the preview would show "not signed in".

> [!WARNING]
>
> `.env` stays on your computer. Never commit it or share the token in it.

## Step 4: Open the preview

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

Open `http://localhost:3001`. The starter page shows your name, your organization and the add-on name. Your preview now talks to your real account, with the app's own components and styles.

If the app was updated while the preview was running, stop it and run `pnpm dev` again. Reloading the page is not enough.

## Step 5: Build your add-on file

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

The build checks your code first and stops on any error. On success it produces one file:

```
dist/static/js/delivery_summary.js
```

That file is your add-on. Next, replace the starter page with your own: see [Building an Add-on](https://docsv4.mile.app/pages/add-ons/sdk/building-an-add-on.md).

> [!TIP]
>
> Keep the SDK in its own folder. If a copy of the app's own source code sits in the folder next to it, the build also checks that code and can fail on errors that are not yours.


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