Kontent.ai Custom App Starter (React)

A React starter template for building Kontent.ai Custom Apps. Get your custom app up and running in minutes.

🚀 Quick Start

1. Setup the Project

# Use this template or clone
git clone https://github.com/mberry1989/custom-app-starter-react.git
cd custom-app-starter-react

# Install dependencies
npm install

# Start development
npm run dev

Note: Kontent.ai requires HTTPS for custom apps. See the Local Development section for HTTPS setup options.

2. Configure in Kontent.ai

1. Go to Environment settings → Custom apps in your Kontent.ai project
2. Create a new custom app
3. Set the App URL to your development server (must be HTTPS)
4. Add optional JSON configuration if needed
5. Save and add the app to your navigation

3. Start Building

Edit src/IntegrationApp.tsx to build your custom app. The starter provides:

• ✅ Complete SDK integration - Ready to use Kontent.ai data
• ✅ TypeScript support - Fully typed for great DX
• ✅ Error handling - Helpful messages when not in iframe
• ✅ Kontent.ai styling - Matches the CMS interface
• ✅ Development setup - HTTPS and hot reload ready

🎣 Available Hooks

Access Kontent.ai data with these React hooks:

import { useConfig, useEnvironmentId, useUserInfo, useUserRoles } from './hooks';

function MyComponent() {
  const config = useConfig();           // Your app configuration
  const environmentId = useEnvironmentId(); // Current environment ID
  const userInfo = useUserInfo();       // Current user details
  const userRoles = useUserRoles();     // User permissions
  
  return <div>Environment: {environmentId}</div>;
}

⚙️ Configuration

Pass configuration to your app via JSON in the Kontent.ai interface:

{
  "apiUrl": "https://api.example.com",
  "theme": "light",
  "maxItems": 100
}

Access it in your components:

function MyComponent() {
  const config = useConfig();
  const apiUrl = config?.apiUrl as string;
  
  return <div>API: {apiUrl}</div>;
}

🔧 Local Development

Kontent.ai requires HTTPS for custom apps. This project automatically generates self-signed certificates using Vite's basic SSL plugin.

Automatic HTTPS (Default)

# Start development with automatic HTTPS
npm run dev

Your app will be available at https://localhost:3000 with automatically generated certificates.

Note: Your browser will show a security warning for self-signed certificates. Click "Advanced" → "Proceed to localhost" to continue.

Alternative HTTPS Solutions

If you prefer other solutions:

• Cloudflare Tunnel: cloudflared tunnel --url http://localhost:3000
• ngrok: ngrok http 3000 (use the HTTPS URL)
• Reverse proxy: nginx, Caddy, or similar with SSL termination
• IDE extensions: Some editors provide HTTPS dev servers

✨ Code Quality

This project uses the official Kontent.ai Biome configuration for consistent formatting and linting:

# Check code quality
npm run lint

# Auto-fix issues  
npm run lint:fix

# Format code
npm run format

📁 Project Structure

src/
├── components/          # React components
├── hooks/              # Kontent.ai data hooks  
├── types.ts            # TypeScript definitions
├── App.tsx             # Root component with error handling
├── IntegrationApp.tsx  # 👈 Build your app here
└── main.tsx            # Application entry point

🚀 Deploy Your App

1. Build the app:

   npm run build

2. Deploy to your hosting platform (Vercel, Netlify, etc.)

3. Update the App URL in Kontent.ai to your deployed URL

4. Test the integration - Your app should load within Kontent.ai

🔗 Learn More

• Custom Apps Documentation
• Custom App SDK
• Kontent.ai Develop Section

---

Ready to build? Start editing src/IntegrationApp.tsx and create something amazing! 🎉