Getting Started

Prerequisites

• Node.js and npm installed
• Your license key (provided after purchase)
• Your npm authentication token (sent via email)

1. Configure npm authentication

To install Kottster Pro packages, npm needs your authentication token. Add a .npmrc file to your project root (same folder as package.json) with your token.

The file should contain:

//registry.npmjs.org/:_authToken=npm_YOUR_TOKEN_HERE

Replace npm_YOUR_TOKEN_HERE with the actual token you received.

2. Install the packages

Before installing, ensure your project has the latest Kottster core packages (@kottster/common, @kottster/server, @kottster/react) installed. All of core and Professional packages listed below must be on the same version.

Install the following packages:

• @kottster-pro/react
• @kottster-pro/server

Example using npm:

npm install @kottster-pro/react @kottster-pro/server

If installation fails with an authentication error, check that your .npmrc file is in the correct location and contains the correct token.

3. Activate the license

You need to activate the license on both server and client sides.

Server side

In your main server file (app/_server/app.js), import the activate function from @kottster-pro/server and pass it to the professional property in your createApp configuration:

import { createApp } from '@kottster/server';
import { activate } from '@kottster-pro/server';
import schema from '../../kottster-app.json';

export const app = createApp({
  schema,
  secretKey: '<YOUR_SECRET_KEY>',
  kottsterApiToken: '<YOUR_KOTTSTER_API_TOKEN>',

  professional: activate({
    license: 'YOUR_LICENSE_KEY',
  }),

  // Other configuration...
});

We recommend storing sensitive information in environment variables instead of hardcoding them:

export const app = createApp({
  schema,
  secretKey: process.env.KOTTSTER_SECRET_KEY,
  kottsterApiToken: process.env.KOTTSTER_API_TOKEN,

  professional: activate({
    license: process.env.KOTTSTER_LICENSE,
  }),

  // Other configuration...
});

Client side

In your main client file (app/main.jsx), import KottsterProProvider from @kottster-pro/react and wrap your KottsterApp component with it:

import React from 'react';
import ReactDOM from 'react-dom/client';
import { KottsterApp } from '@kottster/react';
import { KottsterProProvider } from '@kottster-pro/react';
import '@kottster/react/dist/style.css';

const pageEntries = import.meta.glob('./pages/**/index.{jsx,tsx}', { eager: true });

ReactDOM.createRoot(document.getElementById('root')!).render(
  <React.StrictMode>
    <KottsterProProvider>
      <KottsterApp pageEntries={pageEntries} />
    </KottsterProProvider>
  </React.StrictMode>
);

Verify the setup

Start your app and check the console for errors. No errors related to the Professional plan or license verification should appear.

In production, the app verifies your license via HTTP requests:

• Server side: POST https://api.kottster.app/v3/apps/license/verify
• Client side: GET https://api.kottster.app/v3/apps/license-public-token/verify/*

4. Connect Keycloak (optional)

This step is optional. If you want to use Keycloak as your identity provider, follow these instructions.

4.1. Install the package

Install the @kottster-pro/keycloak package:

npm install @kottster-pro/keycloak

Unlike other Professional packages, @kottster-pro/keycloak has its own versioning and may not match the core and other Professional packages' versions.

4.2. Create a Keycloak client

1. Open your Keycloak admin console
2. Select your realm (or create a new one)
3. Go to Clients → Create Client
4. Configure the client:
   • Client Type: Select OpenID Connect
   • Client ID: Use a descriptive identifier (e.g., kottster-admin-panel)
   • Valid Redirect URIs: Add your application's redirect URLs. By default, your Kottster app uses the /idp/callback path. For local development on the default port, add http://localhost:5480/idp/callback or any other port you use. Don't forget to add your live site URLs as well (e.g., https://your-domain.com/idp/callback).
5. Save the client

Recommendation

We recommend going to Client Settings → Advanced Settings and set “Access Token Lifespan” to at least 30 minutes to avoid frequent re-authentication

4.3. Configure your Kottster app

In your server file, import connectKeycloak from @kottster-pro/keycloak and use it as your identityProvider:

import { createApp } from '@kottster/server';
import { activate } from '@kottster-pro/server';
import { connectKeycloak } from '@kottster-pro/keycloak';
import schema from '../../kottster-app.json';

export const app = createApp({
  schema,
  secretKey: '<YOUR_SECRET_KEY>',
  kottsterApiToken: '<YOUR_KOTTSTER_API_TOKEN>',

  professional: activate({
    license: 'YOUR_LICENSE_KEY',
  }),

  identityProvider: connectKeycloak({
    baseUrl: 'http://localhost:8080',
    realm: 'master',
    clientId: 'your-client-id',
    availableClientRoles: [
      'Manager',
      'Editor',
      'Moderator'
    ],
  }),
});

Learn more about the configuration options in the connectKeycloak section.

We recommend using environment variables for Keycloak configuration as well:

export const app = createApp({
  schema,
  secretKey: process.env.KOTTSTER_SECRET_KEY,
  kottsterApiToken: process.env.KOTTSTER_API_TOKEN,

  professional: activate({
    license: process.env.KOTTSTER_LICENSE,
  }),

  identityProvider: connectKeycloak({
    baseUrl: process.env.KEYCLOAK_BASE_URL,
    realm: 'master',
    clientId: process.env.KEYCLOAK_CLIENT_ID,
    availableClientRoles: [
      process.env.KEYCLOAK_ROLE_MANAGER,
      process.env.KEYCLOAK_ROLE_EDITOR,
      process.env.KEYCLOAK_ROLE_MODERATOR
    ],
  }),
});

4.3. Different identity providers for development and production

We recommend using the default SQLite-based identity provider for development and Keycloak only for production. This makes it easier to run the app locally without needing access to a Keycloak server.

import { createApp, createIdentityProvider } from '@kottster/server';
import { activate } from '@kottster-pro/server';
import { connectKeycloak } from '@kottster-pro/keycloak';
import schema from '../../kottster-app.json';

const isProduction = process.env.NODE_ENV === 'production';

const identityProvider = isProduction
  ? connectKeycloak({
      baseUrl: 'http://localhost:8080',
      realm: 'master',
      clientId: 'CLIENT_ID_HERE',
    })
  : createIdentityProvider('sqlite', {
      fileName: 'app.db',
      passwordHashAlgorithm: 'bcrypt',
      jwtSecretSalt: 'JWT_SECRET_SALT',
      rootUsername: 'admin',
      rootPassword: 'admin',
    });

export const app = createApp({
  schema,
  secretKey: process.env.KOTTSTER_SECRET_KEY,
  kottsterApiToken: process.env.KOTTSTER_API_TOKEN,

  professional: activate({
    license: process.env.KOTTSTER_LICENSE,
  }),

  identityProvider,
});

Verify Keycloak integration

Go to your app's login page. You should see a Sign In with SSO button that redirects to Keycloak.

Important

Keep role names identical regardless of which identity provider you use or which environment the app runs in. Role names are case-sensitive and stored in page configurations. If role names don't match, users won't be able to access certain pages even if they have the correct roles in Keycloak.