Skip to main content
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: 
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. 
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. 
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

You can deploy your app anywhere, but we recommend Fly.io for its simplicity and performance. The app template includes a fly.toml ready for deployment: 
# 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
Your app must be accessible over HTTPS. The Max AI platform will embed your app via iframe, which requires a secure connection.

​
CLI (Coming Soon)

A Max AI CLI is coming soon that will let you scaffold new apps, manage API keys, and test locally with a single command.

​
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)

​
Performance

  • Use pagination efficiently — request only the data you need (see 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