Questa guida crea una piccola app browser che legge il tema di Kucedr e salva un contatore di aperture nello spazio dati dell’app. Kucedr apre l’HTML compilato in una finestra dedicata e fornisce il bridge dell’SDK durante l’esecuzione.

Prerequisiti

  • Kucedr installato e in esecuzione.
  • Node.js 18 o successivo e npm.
  • Un checkout locale del repository di Kucedr finché il pacchetto SDK non sarà pubblicato su npm.

1. Crea Il Progetto

Crea un progetto TypeScript vanilla con Vite, quindi installa l’SDK dal checkout di Kucedr:

npm create vite@latest hello-kucedr -- --template vanilla-ts
cd hello-kucedr
npm install
npm install /percorso/assoluto/kucedr/packages/sdk

Puoi usare qualsiasi strumento di build per il browser. L’unico risultato obbligatorio è un file HTML locale, con le sue risorse, dentro la cartella dell’app.

2. Aggiungi Il Manifest Dell’App

Crea manifest.json nella radice del progetto:

{
  "title": "Hello Kucedr",
  "description": "Un’app minima creata con l’SDK di Kucedr.",
  "metadata": {
    "version": "0.1.0",
    "category": "utility",
    "entry": "dist/index.html"
  }
}

Tutti i campi sono obbligatori. L’entry deve essere un percorso relativo a un file HTML dentro la cartella dell’app. Kucedr accetta anche un package.json standard con name, description e version non vuoti e un percorso HTML locale in main o exports. Un manifest dedicato è più chiaro per distribuire l’app.

3. Usa L’SDK

Sostituisci src/main.ts con:

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

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

if (!root) throw new Error('Elemento #app mancante');

if (!isKucedr()) {
  root.textContent = 'Apri questa build dentro 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 = `Aperta in Kucedr ${visits + 1} volte.`;
}

Il tipo generico passato a getExtensionStoreValue() è un’asserzione TypeScript, non una validazione a runtime. Valida i dati salvati prima di usarli quando hanno una struttura più complessa di questo contatore.

4. Compila L’App

npm run build

Verifica che dist/index.html esista e che l’entry in manifest.json coincida. Mantieni insieme manifest.json, dist/index.html e tutte le risorse generate quando sposti o condividi la cartella.

5. Importa E Apri L’App

  1. Apri le Impostazioni di Kucedr.
  2. Vai in Impostazioni → App.
  3. Scegli Importa, poi seleziona la cartella hello-kucedr.
  4. Usa Dettagli per ispezionarla oppure Apri per avviarla.

Kucedr copia la cartella selezionata in ~/.kucedr/apps/<id>, escludendo node_modules. Ricompila la cartella sorgente e importala di nuovo per aggiornare l'app gestita conservando la sua cartella data.

Durante lo sviluppo, scegli Debug e seleziona una cartella esterna dell'app. Kucedr esegue direttamente da quella cartella l'entry già compilata, senza copiarla. La rimozione della registrazione Debug conserva sia la cartella sorgente sia i dati dell'app.

Sviluppo Fuori Da Kucedr

isKucedr() restituisce false in un browser normale. Separa rendering e logica di dominio dalle chiamate all’host, così gran parte dell’interfaccia può funzionare con il tuo server di sviluppo. Racchiudi l’accesso all’SDK in piccole funzioni e usa dati di anteprima durante lo sviluppo.

Passi Successivi

  • Consulta il Riferimento API Dell’SDK per spazio dati, modelli, controlli nativi della finestra e client esterno.
  • Usa win.setTitlebarOptions() se l’app richiede azioni nella barra del titolo gestita dall’host.
  • Usa app.writeExtensionStoreFile() per file binari o di testo di proprietà dell’app.
  • Verifica isKucedr() prima di usare un’API disponibile solo dentro Kucedr.