Platforms

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

// kitrrc.ts
import { defineKitrConfig } from '@kitr/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({ 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

Override any option at run time with an environment variable or a flag: KITR_SITE_PORT=4000 kitr dev site or kitr dev site --port 4000.

kitr doctor also checks each platform's tools, such as the Rust toolchain for Tauri.

Options

Every platform takes without, whatever its type:

web (@kitr/web)

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

server (@kitr/server)

desktop (@kitr/desktop, Electron)

The Electron code lives in platforms/<name>/. Electron is the recommended desktop shell: it ships its own browser, so every user sees what you tested. See desktop.

tauri (@kitr/tauri)

Same options as desktop. The Rust project lives in platforms/<name>/src-tauri and needs the Rust toolchain. Downloads are small, but the system webview can render differently between machines. Pick desktop or tauri, not both. See tauri.

mobile (@kitr/mobile)

Hooks like usePlatform() and useBackButton() work the same in the browser and on the phone. See mobile.

Where the code runs: runtime, platform and form factor

Three separate questions, three APIs:

What each environment answers. Electron and Tauri are both type: 'desktop'; only the runtime tells them apart.

detectRuntime() only reads globals, so it is safe to call anywhere, including on the server.

Device packages on each runtime

The five device packages (native, notifications, files, secure-storage, updater) pick a driver for the runtime they run in. When a native runtime has no driver, they throw E_DRIVER_UNAVAILABLE instead of quietly running browser code. Set fallbackToWeb: true in the package's config to use the browser driver anyway.

kitr add <package> installs the plugins each of your platforms needs. On Capacitor:

A missing plugin throws E_DRIVER_UNAVAILABLE with the plugin to install.

One project, every platform

examples/everywhere is one project with a website, an Electron app and a Capacitor app:

// kitrrc.ts
platforms: {
  site: web({ mode: 'spa' }),
  app: desktop(),
  phone: mobile(),
},

It is the app kit plus kitr add desktop app, kitr add mobile phone, kitr add secure-storage and kitr add notifications. Add the platforms first, so the device packages see Capacitor and install its plugins.

Branch on the shell in code:

import { detectRuntime } from '@kitr/platform'

if (detectRuntime() === 'electron') {
  // Electron only. In components, use useRuntime().
}
if (import.meta.env.KITR_PLATFORM === 'phone') {
  // Only in the build of the platform named phone. Other builds drop this branch.
}

Use the runtime for what the shell can do. Use KITR_PLATFORM for what to ship. To add your own state or a different driver, see Extending kitr.

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, ...)
  <platform>/        # files that replace a shared one for one platform's build
platforms/
  app/               # desktop: the Electron main/preload sources; tauri: src-tauri/
  phone/             # mobile: capacitor.config.ts, ios/, android/
dist/<name>/         # build output per platform
kitrrc.ts

One project, several apps

A site, an admin, an API, a phone app and a desktop app can be one project or several. Pick by what they share:

With platforms, each build can differ in three ways: its config files, the packages it leaves out, and its pages.

Config per platform

A file in config/<platform>/ replaces the shared file of the same name, for that platform's build only:

config/
  theme.ts         # every build
  flags.ts
  admin/
    theme.ts       # the admin build uses this instead of config/theme.ts
  phone/
    flags.ts

The file replaces the shared one. Nothing is merged. To change a few keys, spread the shared file:

// config/admin/theme.ts
import { defineConfig } from '@kitr/theme'
import base from '../theme'

export default defineConfig({ ...base, default: 'dark' })

The folder name must be a platform name; kitr doctor warns about any other folder in config/. kitr platforms lists the config files each platform uses and where each comes from. For a one-line difference, forPlatform() inside the shared file is enough.

Leave a package out

without takes packages out of one build. Name them as in packages, with or without @kitr/:

platforms: {
  www: web({ mode: 'ssr' }),
  admin: web({ mode: 'spa', port: 3002, without: ['analytics', 'consent'] }),
  phone: mobile({ without: ['analytics'] }),
},

That build has neither the package's provider nor its config/<name>.ts, so app.container.has('analytics') is false there. kitr config admin without analytics,consent sets it. A name that is not in packages is a kitr doctor error. A service only one platform needs is a provider that returns early unless app.platform is that platform.

Flags per platform

Keep one flags service and split the definitions into groups:

// app/flags/mobile.ts
export const mobileFlags = defineFlags({ 'offline-sync': { default: false } })

// app/flags/desktop.ts
export const desktopFlags = defineFlags({ 'menu-bar': { default: true } })

// app/flags.ts: shared code imports this one
export const flags = { ...mobileFlags, ...desktopFlags }

config/flags.ts lists flags, so the web and server builds see every flag. config/phone/flags.ts lists mobileFlags and config/desk/flags.ts lists desktopFlags. Each file can also use its own providers.

Theme per platform

config/admin/theme.ts spreads the shared theme and changes default, colors or tokens. Styles in app/styles/ stay shared. Two versions of a package in one project are not possible; that is a workspace.

Pages per platform

The rest of the toolbox works per platform too: ssrRoute({ www: true, default: false }) in @kitr/seo, forPlatform() and perPlatform() in @kitr/platform, <Only>, <Except> and useFormFactor() in @kitr/platform/react, and the stacks in @kitr/router/stack. For apps in separate projects, see Workspaces.

Writing a platform package

import { definePlatform } from '@kitr/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'],       // packages `kitr add kiosk <name>` adds 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 has the platform name, the project root, the options, the command-line flags and log, run and exec helpers.

A shell around the web build (like Electron, Tauri or Capacitor) can reuse the shared steps: shellPlatformHooks() from @kitr/platform/cli for dev, build and doctor, and createShellProvider() from @kitr/platform/shell for the runtime drivers. desktop, tauri and mobile are built this way.