This guide creates a small browser app that reads Kucedr's theme and stores a visit counter in app-owned storage. Kucedr opens the built HTML in a dedicated window and supplies the SDK bridge at runtime.

Prerequisites

  • Kucedr installed and running.
  • Node.js 18 or newer and npm.
  • A local checkout of the Kucedr repository while the SDK package is not yet published to npm.

1. Create The Project

Create a vanilla TypeScript project with Vite, then install the SDK from your Kucedr checkout:

npm create vite@latest hello-kucedr -- --template vanilla-ts
cd hello-kucedr
npm install
npm install /absolute/path/to/kucedr/packages/sdk

Any browser build tool is valid. The only required output is a local HTML file and its assets inside the app folder.

2. Add The App Manifest

Create manifest.json in the project root:

{
  "title": "Hello Kucedr",
  "description": "A minimal app built with the Kucedr SDK.",
  "metadata": {
    "version": "0.1.0",
    "category": "utility",
    "entry": "dist/index.html"
  }
}

Every field is required. The entry must be a relative path to an HTML file inside the app folder. Kucedr also accepts a standard package.json when it contains a non-empty name, description, and version, plus a local HTML path in main or exports. A dedicated manifest is clearer when distributing an app.

3. Use The SDK

Replace src/main.ts with:

import { app, isKucedr, type AppThemeData } from '@kucedr/sdk';

const root = document.querySelector<HTMLDivElement>('#app');

if (!root) throw new Error('Missing #app element');

if (!isKucedr()) {
  root.textContent = 'Open this build inside Kucedr.';
} else {
  const applyTheme = (theme: AppThemeData) => {
    document.documentElement.dataset.theme = theme.isDark ? 'dark' : 'light';
  };

  applyTheme(await app.getThemeData());
  app.onThemeModeChanged(applyTheme);

  const visits = (await app.getExtensionStoreValue<number>('visits')) ?? 0;
  await app.setExtensionStoreValue('visits', visits + 1);

  root.textContent = `Opened in Kucedr ${visits + 1} time${visits === 0 ? '' : 's'}.`;
}

The generic type passed to getExtensionStoreValue() is a TypeScript assertion, not runtime validation. Validate stored data before using it when its shape is more complex than this counter.

4. Build The App

npm run build

Verify that dist/index.html exists and that the entry in manifest.json matches it. Keep manifest.json, dist/index.html, and every generated asset together when you move or share the folder.

5. Import And Open It

  1. Open Kucedr Settings.
  2. Go to Settings → Apps.
  3. Choose Import, then select the hello-kucedr folder.
  4. Use Details to inspect it or Open to launch it.

Kucedr copies the selected folder into ~/.kucedr/apps/<id>, excluding node_modules. Rebuild your source folder and import it again to refresh the managed app while preserving its data folder.

For development, choose Debug and select an external app folder. Kucedr runs the built entry directly from that folder without copying it. Unregistering the debug app preserves the source folder and app-owned data.

Development Outside Kucedr

isKucedr() returns false in a normal browser. Keep rendering and domain logic separate from host calls so most of the interface can run under your usual development server. Put SDK access behind small functions and provide preview data while developing.

Next Steps

  • Read the SDK API Reference for storage, models, native window controls, and the external client.
  • Use win.setTitlebarOptions() when your app needs host-rendered titlebar actions.
  • Use app.writeExtensionStoreFile() for binary or text files owned by the app.
  • Check isKucedr() before using an embedded-only API.