Platforms

Where an app runs is a platform: a named entry in kitrrc.ts built by a factory from a platform package. The core knows only the contract (definePlatform in @kitr/core); each package owns its options, its scaffold, its dev server and its build.

// kitrrc.ts
import { defineKitrConfig } from 'kitr/app'
import { web } from 'kitr/web'
import { server } from 'kitr/server'
import { desktop } from 'kitr/desktop'

export default defineKitrConfig({
  platforms: {
    site: web({ mode: 'ssr', pwa: true }),
    api: server({ runtime: 'node', port: 3001 }),
    app: desktop({ shell: 'tauri', title: 'My App' }),
  },
  packages: [...],
  providers: [...],
})

Names are yours. One project can hold several platforms of the same type (admin: web({...}), www: web({...})), and every command addresses them by name.

Commands

Every option can be overridden at run time without touching the file: KITR_SITE_PORT=4000 kitr dev site, or kitr dev site --port 4000. The name is upper-cased with non-alphanumerics turned into _.

kitr doctor runs each platform's own checks (the Rust toolchain for Tauri, Xcode and Android Studio for Capacitor, wrangler for Workers).

Options

web (@kitr/web)

Prerendering, the sitemap and robots.txt come from config/seo.ts (kitr add seo).

server (@kitr/server)

desktop (@kitr/desktop)

kitr/desktop/client tells which shell is running (isTauri, isElectron, desktopShell); kitr/desktop/tauri has defineCommands, commandQuery, commandMutation and useTauriEvent, kitr/desktop/electron the typed IPC bridge with kitr/desktop/electron-main and kitr/desktop/electron-preload for the other two processes. kitr/desktop/provider registers the platform and storage drivers for the shell in use.

mobile (@kitr/mobile)

kitr/mobile/provider registers the Capacitor drivers; kitr/platform/react (usePlatform, useAppState, useBackButton, useDeepLink, useSafeArea) and kitr/storage then answer the same way in the browser and in the shell.

Layout

app/                 # routes, components, features, channels: shared by every UI platform
server/
  main.ts            # the server platform entry (createServer + routes + realtime)
  routes.ts          # defineRoutes(...)
  controllers/
  realtime.ts        # createRealtimeServer({ channels })
config/              # one file per package (config/seo.ts, config/realtime.ts, config/theme.ts, ...)
platforms/
  app/               # desktop: src-tauri/ or the Electron main/preload sources
  phone/             # mobile: capacitor.config.ts, ios/, android/
dist/<name>/         # build output per platform
kitrrc.ts

Writing a platform package

import { definePlatform } from 'kitr/app'

export const kiosk = definePlatform<{ port?: number }>(
  {
    type: 'kiosk',
    description: 'Fullscreen Chromium on a Raspberry Pi',
    describe: { port: { type: 'number', default: 3300, description: 'Dev server port' } },
    requires: ['router', 'platform'],       // recipes `kitr add kiosk <name>` runs first
    provider: '@acme/kitr-kiosk/provider',  // registered in kitrrc.ts providers
  },
  (options) => ({
    dependencies: { chromium: '^1.0.0' },
    async scaffold(ctx) { await ctx.write('kiosk.json', '{}') },
    async dev(ctx) { await ctx.exec('vite', ['--port', String(options.port)]) },
    async build(ctx) { await ctx.exec('vite', ['build', '--outDir', ctx.dir('dist')]) },
    async start(ctx) { await ctx.exec('chromium', ['--kiosk', `http://localhost:${options.port}`]) },
    async doctor(ctx) { return [] },
    agents: 'Run `kitr dev kiosk` and open the window on the Pi.',
  }),
)

ctx carries the platform name, the project root, the resolved options, the package manager, the other platforms, the flags from the command line, an abort signal and log, run and exec helpers that resolve node_modules/.bin. kitr/vite reads import.meta.env.KITR_PLATFORM and KITR_PLATFORM_TYPE so app code can branch per platform at build time.