Skip to content

getting-started.md

Latest commit

 

History

History
174 lines (130 loc) · 4.27 KB

getting-started.md

File metadata and controls

174 lines (130 loc) · 4.27 KB
Raw

Getting Started

Need a faster setup path? See 5-Minute Onboarding.

Prerequisites

Create a Project

npm create @voltkit/volt my-app
cd my-app

You'll be prompted to choose a framework:

  • Vanilla TypeScript - Minimal setup, no framework
  • React - React + TypeScript template
  • Svelte - Svelte + TypeScript template
  • Vue - Vue + TypeScript template
  • Enterprise - Vanilla TypeScript plus enterprise packaging defaults (volt doctor, volt package, ADMX/docs bundle config)

Project Structure

my-app/
|-- volt.config.ts          # Application configuration
|-- package.json
|-- vite.config.ts          # Vite build configuration (React/Svelte/Vue templates)
|-- tsconfig.json
|-- index.html
`-- src/
    |-- main.ts / main.tsx  # Frontend entry point (framework-dependent)
    |-- App.*               # Framework templates (React/Vue/Svelte)
    `-- style.css           # Template styles

Development Workflow

cd my-app

# Install dependencies
npm install

# Start development (Vite dev server + native window)
npm run dev

This opens a native desktop window with your app loaded from the Vite dev server. Hot module replacement works automatically.

Configuration

Edit volt.config.ts to configure your app:

import { defineConfig } from 'voltkit';

export default defineConfig({
  name: 'My App',
  version: '1.0.0',
  window: {
    width: 1024,
    height: 768,
    title: 'My App',
    minWidth: 400,
    minHeight: 300,
  },
  permissions: ['clipboard', 'dialog', 'fs'],
});

See Configuration Reference for all options.

Building for Production

# Build the frontend + native binary
npm run build

The output is in dist-volt/. The runtime artifact includes all frontend assets embedded.

Packaging

# Check prerequisites for packaging/signing on your machine
volt doctor

# Create platform-specific installer
npm run package

This produces:

  • Windows: NSIS installer (.exe)
  • Windows (optional): MSIX package (npm run package -- --format msix)
  • macOS: .app bundle (optionally .dmg)
  • Linux: AppImage and .deb

Adding Capabilities

To use native APIs, declare permissions in volt.config.ts and import from voltkit:

// volt.config.ts
export default defineConfig({
  name: 'My App',
  permissions: ['clipboard', 'notification'],
});
// In your main process code
import { clipboard, Notification } from 'voltkit';

// Read clipboard
const text = clipboard.readText();

// Show notification
new Notification({ title: 'Hello', body: 'From Volt!' }).show();

IPC Communication

Register handlers in the main process, invoke them from the renderer:

// Main process
import { ipcMain } from 'voltkit';

ipcMain.handle('get-data', async (args) => {
  return { items: ['a', 'b', 'c'], query: args.query };
});
// Renderer (in your frontend code)
import { invoke } from 'voltkit/renderer';

const result = await invoke('get-data', { query: 'search' });
console.log(result.items); // ['a', 'b', 'c']

Use raw invoke() for app-defined channels. For built-in high-volume helpers, prefer Volt's renderer APIs:

import { data, workflow } from 'voltkit/renderer';

const profile = await data.profile({ datasetSize: 10_000 });
const query = await data.query({
  datasetSize: 10_000,
  iterations: 4,
  searchTerm: 'risk',
});

const plugins = await workflow.listPlugins();
const result = await workflow.run({
  batchSize: 3_000,
  passes: 3,
  pipeline: plugins.map((plugin) => plugin.name),
});

This keeps renderer code in TypeScript while routing the expensive data and workflow loops through Volt's native runtime path.

Next Steps