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

# App Development

> Build your Max AI marketplace app with the template, SDK, and best practices

Max AI provides tools to help you build marketplace apps quickly — a template app, SDK packages, and deployment guidance.

## App Template

The fastest way to get started is by cloning the official app template:

```bash theme={null}
git clone https://github.com/maxcare-ai/max-app-template
cd max-app-template
npm install
npm run dev
```

The template includes:

* Pre-configured authentication with the Max AI platform
* SDK packages (`@max-ai/components` and `@max-ai/app-bridge`) already installed
* Example pages showing how to fetch and display clinic data
* Ready-to-deploy configuration

## SDK Packages

Two npm packages are available for building Max AI apps:

### @max-ai/components

A component library that provides UI elements matching the Max AI design system. Use these to build interfaces that feel native to the Max AI platform.

```bash theme={null}
npm install @max-ai/components
```

### @max-ai/app-bridge

Handles communication between your app and the Max AI platform. This is used for embedding your app within the Max AI dashboard, exchanging authentication tokens, and receiving context about the current user and organization.

```bash theme={null}
npm install @max-ai/app-bridge
```

## App Lifecycle

### 1. Draft

When you create a new app, it starts in **Draft** status. You can configure settings, set required scopes, and develop locally.

### 2. Submit for Review

When your app is ready, submit it for review from the app settings page. The Max AI team will review your app's:

* Functionality and UX
* Required scopes (are they justified?)
* Security practices
* Data handling

### 3. Approved / Denied

The Max AI team will approve or deny your submission with feedback. If denied, you can address the feedback and resubmit.

### 4. Live

Once approved, your app becomes available in the Max AI marketplace. Clinics can discover and install it, granting your app access to their data through the approved scopes.

## Deployment (Beta)

<Info>
  App deployment is currently in **beta**. The deployment workflow may change as we refine the experience.
</Info>

You can deploy your app anywhere, but we recommend **[Fly.io](https://fly.io)** for its simplicity and performance. The app template includes a `fly.toml` ready for deployment:

```bash theme={null}
# Install Fly CLI
curl -L https://fly.io/install.sh | sh

# Deploy
fly launch
fly deploy
```

Other supported hosting options:

* **Vercel** — Great for Next.js apps
* **Railway** — Simple container deployments
* **AWS / GCP / Azure** — For full infrastructure control
* **Any platform** that can run a Node.js application

<Note>
  Your app must be accessible over HTTPS. The Max AI platform will embed your app via iframe, which requires a secure connection.
</Note>

## CLI

The Max AI CLI (`@max-ai/cli`) is the recommended way to create, develop, and deploy apps. It handles authentication, project scaffolding, local tunneling, and deployment in a single tool.

```bash theme={null}
npm install -g @max-ai/cli

max-ai auth login        # Authenticate with your developer account
max-ai app init my-app   # Create and scaffold a new app
cd my-app
max-ai app dev           # Start dev server + tunnel + register draft
max-ai app deploy        # Deploy to production (beta)
```

<Card title="CLI Reference" icon="terminal" href="/guides/cli">
  Full CLI documentation with all commands and options.
</Card>

## Best Practices

### Security

* Store API keys in environment variables, never in source code
* Validate all data received from the API before using it
* Use HTTPS for all communications
* Implement proper error handling (see [Error Handling](/guides/errors))

### Performance

* Use pagination efficiently — request only the data you need (see [Pagination](/guides/pagination))
* Cache responses where appropriate (e.g., provider and facility lists change infrequently)
* Implement retry logic with exponential backoff for transient errors

### User Experience

* Use `@max-ai/components` for a consistent look and feel
* Show loading states while data is being fetched
* Handle error states gracefully with user-friendly messages
* Display the `trace_id` in error states so users can report issues