veloxkit.config.ts

The single configuration file for your VeloxKit app. Lives at the project root and is executed by the CLI at build/dev time to produce a resolved JSON config.

import { defineConfig } from 'veloxkit'
 
export default defineConfig({
  // ... all fields
})

defineConfig prints the resolved config as JSON to stdout when the file is executed. The CLI reads this output — do not add side effects to veloxkit.config.ts.

`version`

version?: string

App version string, e.g. '1.2.0'. Exposed at runtime via updater.getVersion().

`icon`

icon?: string

Path to a PNG icon (512×512 or 1024×1024 recommended). Used as the window icon and in installers.

`window`

Controls the initial window appearance and rendering backend.

window?: {
  title?:       string
  width?:       number         // Default: 1280
  height?:      number         // Default: 800
  startupMode?: 'windowed' | 'maximized' | 'fullscreen'
  decorations?: boolean        // OS title bar (default: true). false = frameless window
  background?:  string         // GPU clear color before first JS frame: '#rrggbb' or '#rrggbbaa'
  renderMode?:  'auto' | 'gpu' | 'cpu' | 'skia' | 'femtovg'  // Rendering backend (default: 'gpu')
}

`window.background`

The GPU clear color shown before the first React frame renders. Match this to your app's root background color to eliminate the white flash on startup.

window: {
  background: '#1e1e2e',   // matches dark root background
}

`window.decorations`

Set to false for a frameless window with a custom title bar.

window: {
  decorations: false,
}

`window.renderMode`

Controls the rendering backend:

Value	Description
`'auto'`	Auto-detect: uses `gpu` on real hardware, `cpu` on software adapters (recommended for production)
`'gpu'`	GPU compute via wgpu (best performance, requires DX12/Metal/Vulkan)
`'cpu'`	Vello's built-in CPU path; still uses wgpu for the final blit
`'skia'`	Skia-based renderer — platform-native text, PDF export
`'femtovg'`	FemtoVG OpenGL renderer — older hardware / embedded Linux

Can also be forced at runtime via the VELOX_CPU_RENDER=1 environment variable. Useful for CI, testing, or devices without a supported GPU.

`capabilities`

Declares which system APIs your app can access. All capabilities are opt-in — undeclared APIs throw at runtime.

capabilities?: {
  // File system
  fs?:           { read?: string[]; write?: string[] }
 
  // Network
  network?:      { allow?: string[] }      // origin allowlist
 
  // Environment variables
  env?:          { allow?: string[] }      // variable name allowlist
 
  // Deep linking
  deeplink?:     { scheme: string; singleInstance?: boolean }
 
  // Simple toggles
  db?:           boolean    // SQLite
  dialog?:       boolean    // file/folder picker dialogs
  clipboard?:    boolean    // read/write clipboard
  notification?: boolean    // desktop notifications
  battery?:      boolean    // battery status
  usb?:          boolean    // USB device enumeration
  shell?:        boolean    // spawn shell commands
  mdns?:         boolean    // mDNS service discovery
  system?:       boolean    // OS info, displays, memory
  power?:        boolean    // sleep/wake events
  storage?:      boolean    // app data directory access
  gamepads?:     boolean    // gamepad/controller input
  globalShortcuts?: boolean // OS-level keyboard shortcuts
  credentials?:  boolean    // OS keychain (DPAPI/Keychain/Secret Service)
  audio?:        boolean    // audio playback
  video?:        boolean    // video playback
  camera?:       boolean    // camera capture
  microphone?:   boolean    // microphone recording
  ai?:           boolean    // local AI (embed, generate, transcribe)
  hid?:          boolean    // HID device access
  updater?:      boolean    // auto-updater
  crash?:        boolean    // crash reporting
}

File system scoping

Paths use glob patterns relative to the app's data directory:

capabilities: {
  fs: {
    read:  ['**'],           // read anywhere
    write: ['documents/**'], // write only under documents/
  },
}

Deep linking

capabilities: {
  deeplink: {
    scheme:          'myapp',  // handles myapp:// URLs
    singleInstance:  true,     // focus existing window instead of opening a new one
  },
}

`dev`

Build settings used by veloxkit dev and veloxkit build.

dev?: {
  entry?:  string    // JS entry point (default: 'js/app.jsx')
  output?: string    // Compiled bundle path (default: 'js/dist/app.js')
  watch?:  string[]  // Directories to watch for HMR (default: ['js'])
}

The CLI runs Bun to bundle entry → output on file changes. The output file is loaded by the VeloxKit runtime at startup.

js/dist/ is gitignored by default in new projects. Commit your source (js/app.jsx) but not the compiled bundle.

`splash`

Optional splash screen shown during JS startup.

splash?: {
  image?:     string   // Path to a PNG image, centered on the splash background
  background?: string  // Hex color, e.g. '#1e1e2e'. Defaults to black
  minimumMs?: number   // Minimum display time before hideSplash() takes effect
}

Call veloxWindow.hideSplash() from JS when your app is ready:

import { veloxWindow } from 'veloxkit'
 
// After your data loads:
veloxWindow.hideSplash()

A 30-second safety timeout auto-hides the splash if hideSplash() is never called.

`plugins`

JS plugin extensions. Each plugin's exported async functions become callable via backend.<name>.<fn>() from JS.

plugins?: Array<{
  entry:          string    // Path to the plugin JS entry point (bundled at startup)
  name?:          string    // Optional namespace prefix for the plugin's commands
  capabilities?:  string[]  // Capabilities the plugin requires
}>

plugins: [
  { entry: 'plugins/storage.js', name: 'storage' },
  { entry: 'plugins/analytics.js', name: 'analytics' },
]

See JS Plugins for how to write a plugin.

Full example

import { defineConfig } from 'veloxkit'
 
export default defineConfig({
  version: '1.0.0',
  icon: 'assets/icon.png',
 
  window: {
    title:       'My Notes',
    width:       1200,
    height:      800,
    startupMode: 'windowed',
    background:  '#171923',
    decorations: true,
    renderMode:  'gpu',
  },
 
  capabilities: {
    fs:           { read: ['**'], write: ['documents/**'] },
    network:      { allow: ['https://api.myservice.com'] },
    db:           true,
    dialog:       true,
    clipboard:    true,
    notification: true,
    credentials:  true,
    crash:        true,
    deeplink:     { scheme: 'mynotes', singleInstance: true },
  },
 
  dev: {
    entry:  'js/app.jsx',
    output: 'js/dist/app.js',
    watch:  ['js'],
  },
 
  splash: {
    background: '#171923',
    minimumMs:  800,
  },
})

system Capabilities Reference