Kontent.ai Custom App Starter

A React + TypeScript starter template for building Kontent.ai custom apps. This template provides a quick setup with all the essentials to start developing your custom app.

Features

• ✅ React 18 with TypeScript
• ✅ Vite for fast development and builds
• ✅ HTTPS enabled for local development (self-signed certificate)
• ✅ @kontent-ai/custom-app-sdk integration
• ✅ Custom hook for observing context changes
• ✅ Example implementations of all SDK functions
• ✅ Kontent.ai ESLint & Biome configurations
• ✅ Minimal, clean styling

Getting Started

Prerequisites

• Node.js 18+ and pnpm (or npm)

Installation

Using pnpm (recommended):

pnpm i

Using npm:

npm i

Development

Start the development server:

pnpm dev
# or
npm run dev

The app will be available at https://localhost:5173. The dev server uses a self-signed certificate for HTTPS, which is required for custom apps. Your browser will show a security warning on first access - this is expected for local development.

Build

Build for production:

pnpm build
# or
npm run build

Preview the production build:

pnpm preview
# or
npm run preview

Project Structure

src/
├── hooks/
│   └── useCustomAppContext.ts  # Custom hook for observing context
├── App.tsx                      # Main application component
├── App.css                      # Application styles
├── main.tsx                     # Application entry point
└── index.css                    # Global styles

SDK Usage

Observing Context Changes

The useCustomAppContext hook automatically subscribes to context changes:

import { useCustomAppContext } from './hooks/useCustomAppContext';

const { context, isLoading, error } = useCustomAppContext();

Single Context Fetch

While the SDK provides getCustomAppContext() for fetching the context once without subscribing to changes, we recommend using the reactive useCustomAppContext hook instead. The hook ensures your app stays up-to-date with the latest context automatically.

If you need a single fetch for specific use cases:

import { getCustomAppContext } from '@kontent-ai/custom-app-sdk';

const response = await getCustomAppContext();
if (!response.isError) {
  console.log(response.context);
}

Adjusting Popup Size

Control the size of your custom app when displayed in a popup:

import { setPopupSize } from '@kontent-ai/custom-app-sdk';

await setPopupSize(
  { unit: 'px', value: 800 },  // width
  { unit: 'px', value: 600 }   // height
);

Deploying Your Custom App

1. Build the app: pnpm build
2. Deploy the dist folder to your hosting provider (Netlify, Vercel, etc.)
3. Configure the custom app in Kontent.ai:
   • Go to Environment settings > Custom apps
   • Add a new custom app with your deployed URL
   • Configure the URL pattern where the app should appear
   • Optionally, change the app to the dialog mode

Learn More

• Kontent.ai Custom Apps Documentation
• Custom App SDK Reference
• Kontent.ai ESLint Config
• Kontent.ai Biome Config
• Vite Documentation
• React Documentation

License

MIT