{"id":47300601,"url":"https://github.com/velox-apps/velox","last_synced_at":"2026-03-31T06:00:49.583Z","repository":{"id":316963389,"uuid":"1065490662","full_name":"velox-apps/velox","owner":"velox-apps","description":"Velox is a port of Tauri to Swift.","archived":false,"fork":false,"pushed_at":"2026-02-17T22:38:37.000Z","size":5398,"stargazers_count":323,"open_issues_count":1,"forks_count":3,"subscribers_count":5,"default_branch":"main","last_synced_at":"2026-02-18T04:30:51.252Z","etag":null,"topics":["desktop-app","html","swift","tauri","velox","web-frontend","webview"],"latest_commit_sha":null,"homepage":"https://velox-apps.github.io/velox/documentation/veloxruntime/","language":"Swift","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/velox-apps.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE-APACHE-2.0","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-27T20:48:13.000Z","updated_at":"2026-02-17T22:38:41.000Z","dependencies_parsed_at":"2025-09-28T16:16:12.662Z","dependency_job_id":null,"html_url":"https://github.com/velox-apps/velox","commit_stats":null,"previous_names":["velox-apps/velox"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/velox-apps/velox","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/velox-apps%2Fvelox","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/velox-apps%2Fvelox/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/velox-apps%2Fvelox/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/velox-apps%2Fvelox/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/velox-apps","download_url":"https://codeload.github.com/velox-apps/velox/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/velox-apps%2Fvelox/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31223291,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-31T04:08:55.938Z","status":"ssl_error","status_checked_at":"2026-03-31T04:08:47.883Z","response_time":111,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["desktop-app","html","swift","tauri","velox","web-frontend","webview"],"created_at":"2026-03-17T01:38:19.998Z","updated_at":"2026-03-31T06:00:49.576Z","avatar_url":"https://github.com/velox-apps.png","language":"Swift","funding_links":[],"categories":["Swift"],"sub_categories":[],"readme":"Bringing Tauri to Swift developers.\n\nI love Rust as much as the next security paranoid person, but I do not love it to write apps,\nit gets in my way, and I am too old to develop an appreciation for poetry or Rust.   So this \nis a port of Tauri to Swift so I can both build desktop apps using HTML with Swift backends\nand fill me with joy.\n\nDiscord: [invite](https://discord.gg/nZKv7kkvb)\n\n## Documentation\n\n[Documentation](https://velox-apps.github.io/velox/) and [Tutorials](https://velox-apps.github.io/velox/tutorials/table-of-contents)\n\n## Building\n\nThe Swift package declares a build-tool plugin that automatically compiles the Rust FFI crate\nwhenever `VeloxRuntimeWryFFI` is built. Simply run:\n\n```bash\nswift build\n```\n\nThe plugin will invoke `cargo build` with the correct configuration (`debug` or `release`) and\nemit libraries into `runtime-wry-ffi/target`. If you prefer to build the Rust crate manually you\ncan still run `cargo build` or `cargo build --release` inside `runtime-wry-ffi/`.\n\nBy default the plugin runs Cargo in offline mode to avoid sandboxed network access and ensures\n`velox/.cargo/config.toml` patch overrides are picked up. If you need Cargo to fetch from the\nnetwork, set `VELOX_CARGO_ONLINE=1` when building.\n\n## Create New Projects\n\nUse the [create-velox-app](https://github.com/velox-apps/create-velox-app) command to create a new\nblank project, starting from one of the built-in templates.\n\n## Velox CLI\n\nVelox includes a CLI tool for development workflow, similar to Tauri's CLI.\n\n### Building the CLI\n\n```bash\nswift build --product velox\n```\n\nThe CLI binary will be available at `.build/debug/velox`.\n\n### Commands\n\n#### `velox init` - Initialize a New Project\n\nInitialize Velox in a new or existing directory:\n\n```bash\n# Initialize with defaults (derives name from directory)\nvelox init\n\n# Specify product name and identifier\nvelox init --name \"MyApp\" --identifier \"com.example.myapp\"\n\n# Overwrite existing files\nvelox init --force\n```\n\nThis creates:\n```\nyour-project/\n├── Package.swift       # Swift package manifest\n├── Sources/\n│   └── YourApp/\n│       └── main.swift  # App entry point with IPC handlers\n├── assets/\n│   └── index.html      # Frontend UI template\n└── velox.json          # Velox configuration\n```\n\n#### `velox dev` - Development Mode\n\nRun the app in development mode with hot reloading:\n\n```bash\n# Run with auto-detected target\nvelox dev\n\n# Specify a target explicitly\nvelox dev MyApp\n\n# Run in release mode\nvelox dev --release\n\n# Disable file watching\nvelox dev --no-watch\n\n# Override dev server port\nvelox dev --port 3000\n```\n\nFeatures:\n- Executes `beforeDevCommand` from velox.json (e.g., `npm run dev`)\n- Waits for dev server at `devUrl` if configured\n- Builds and runs the Swift app with `VELOX_DEV_URL` set\n- **Dev server proxy**: When `devUrl` is set, the `app://` protocol proxies requests to your dev server, enabling HMR from tools like Vite\n- Watches for Swift file changes and rebuilds automatically\n- **Smart reload**: Frontend-only changes trigger a quick restart without rebuild\n- Graceful shutdown with Ctrl+C\n\n#### `velox build` - Production Build\n\nBuild the app for production:\n\n```bash\n# Release build (default)\nvelox build\n\n# Debug build\nvelox build --debug\n\n# Create macOS app bundle (.app)\nvelox build --bundle\n\n# Specify target\nvelox build MyApp\n\n# Debug build with app bundle\nvelox build --debug --bundle\n```\n\nThe `--bundle` flag creates a complete macOS app bundle:\n```\n.build/release/MyApp.app/\n├── Contents/\n│   ├── Info.plist      # Generated from velox.json\n│   ├── MacOS/\n│   │   └── MyApp       # Executable\n│   └── Resources/\n│       └── assets/     # Frontend files (from frontendDist)\n```\n\nYou can also set `bundle.active: true` in `velox.json` to enable bundling without the CLI flag.\nFor full macOS bundling details (signing, DMG, notarization), see `Sources/VeloxRuntime/VeloxRuntime.docc/Articles/Bundling.md`.\n\n### Configuration for CLI\n\nThe CLI uses settings from `velox.json`:\n\n```json\n{\n  \"productName\": \"MyApp\",\n  \"version\": \"1.0.0\",\n  \"identifier\": \"com.example.myapp\",\n  \"build\": {\n    \"devUrl\": \"http://localhost:5173\",\n    \"beforeDevCommand\": \"npm run dev\",\n    \"beforeBuildCommand\": \"npm run build\",\n    \"beforeBundleCommand\": \"npm run prepare-bundle\",\n    \"frontendDist\": \"dist\",\n    \"env\": {\n      \"API_URL\": \"https://api.example.com\",\n      \"DEBUG\": \"true\"\n    }\n  },\n  \"bundle\": {\n    \"active\": true,\n    \"targets\": [\"app\", \"dmg\"],\n    \"icon\": \"icons/AppIcon.icns\",\n    \"resources\": [\"extra-assets\"],\n    \"macos\": {\n      \"minimumSystemVersion\": \"13.0\",\n      \"infoPlist\": \"Info.plist\",\n      \"entitlements\": \"entitlements.plist\",\n      \"signingIdentity\": \"Developer ID Application: Example (ABCDE12345)\",\n      \"hardenedRuntime\": true,\n      \"dmg\": {\n        \"enabled\": true,\n        \"name\": \"MyApp\",\n        \"volumeName\": \"MyApp\"\n      },\n      \"notarization\": {\n        \"keychainProfile\": \"AC_NOTARY\",\n        \"wait\": true,\n        \"staple\": true\n      }\n    }\n  }\n}\n```\n\n| Field | Description |\n|-------|-------------|\n| `devUrl` | Dev server URL; enables proxy mode (see below) |\n| `beforeDevCommand` | Command to run before `velox dev` (e.g., start Vite) |\n| `beforeBuildCommand` | Command to run before `velox build` (e.g., build frontend) |\n| `beforeBundleCommand` | Command to run before creating app bundle |\n| `frontendDist` | Directory containing frontend assets for bundling |\n| `env` | Environment variables to inject into build and dev processes |\n\n### Environment Variables\n\nVelox supports environment variable injection from multiple sources:\n\n1. **`.env`** - Base environment file\n2. **`.env.development`** or **`.env.production`** - Mode-specific overrides\n3. **`.env.local`** - Local overrides (gitignored)\n4. **`velox.json` build.env** - Configuration-defined variables\n\nPriority (highest to lowest): system env \u003e velox.json \u003e .env.local \u003e .env.[mode] \u003e .env\n\nExample `.env` file:\n```\nAPI_URL=https://api.example.com\nDEBUG=true\n# Comments are supported\nMULTILINE=\"line1\\nline2\"\n```\n\n### Frontend Development Modes\n\nVelox offers two approaches for serving frontend assets during development. Choose based on your project's complexity and tooling preferences.\n\n#### Option 1: Local Asset Serving (Simple Projects)\n\n**When to use:** Static HTML/CSS/JS without a build step, simple projects, or when you want the fastest possible reload cycle.\n\n```json\n{\n  \"build\": {\n    \"frontendDist\": \"assets\"\n  }\n}\n```\n\n**How it works:**\n- `velox dev` serves files directly from the `frontendDist` directory (e.g., `assets/`)\n- File watcher monitors both Swift sources AND frontend files\n- When you edit `index.html`, `styles.css`, or `app.js`, the app restarts instantly (no rebuild)\n- Swift file changes trigger a full rebuild\n\n**Pros:**\n- Zero configuration - just put HTML files in `assets/`\n- No Node.js or npm required\n- Fastest restart for simple frontend changes\n- Great for prototyping and learning\n\n**Cons:**\n- No transpilation (TypeScript, JSX, etc.)\n- No module bundling\n- No Hot Module Replacement (page fully reloads)\n- Manual browser refresh via app restart\n\n#### Option 2: Dev Server Proxy (Modern Web Tooling)\n\n**When to use:** Projects using Vite, webpack, or other modern frontend toolchains that provide HMR.\n\n```json\n{\n  \"build\": {\n    \"devUrl\": \"http://localhost:5173\",\n    \"beforeDevCommand\": \"npm run dev\",\n    \"frontendDist\": \"dist\"\n  }\n}\n```\n\n**How it works:**\n1. `beforeDevCommand` starts your frontend dev server (e.g., Vite)\n2. Velox waits for `devUrl` to respond before launching the app\n3. The `VELOX_DEV_URL` environment variable is passed to your Swift app\n4. The `app://` protocol proxies all requests to the dev server\n5. File watcher only monitors Swift sources (frontend HMR is handled by Vite)\n\n**Pros:**\n- **Hot Module Replacement (HMR)** - instant updates without page reload\n- Full modern toolchain support (TypeScript, React, Vue, Tailwind, etc.)\n- Source maps for debugging\n- Consistent `app://` protocol between dev and production\n- CORS-free development\n\n**Cons:**\n- Requires Node.js and npm\n- More configuration\n- Slightly slower initial startup (waiting for dev server)\n\n#### Comparison Table\n\n| Feature | Local Assets | Dev Server Proxy |\n|---------|-------------|------------------|\n| Setup complexity | Minimal | Requires npm project |\n| Frontend tooling | None (vanilla JS) | Full (Vite, webpack, etc.) |\n| TypeScript/JSX | Not supported | Fully supported |\n| Hot Module Replacement | No (app restart) | Yes (instant) |\n| Page reload on change | Full restart | Partial/none (HMR) |\n| Swift change handling | Rebuild + restart | Rebuild + restart |\n| Production build | Copy files | Run build command |\n\n#### Switching Between Modes\n\nTo switch from proxy mode to local asset serving, simply remove or comment out `devUrl`:\n\n```json\n{\n  \"build\": {\n    // \"devUrl\": \"http://localhost:5173\",  // Commented out = local mode\n    // \"beforeDevCommand\": \"npm run dev\",   // Not needed without devUrl\n    \"frontendDist\": \"assets\"\n  }\n}\n```\n\nThe same `frontendDist` directory is used for both development (local mode) and production builds.\n\n## Examples\n\nThe repository includes several example applications demonstrating Velox capabilities. Examples are located in the `Examples/` directory.\n\n### Running Examples\n\nBuild and run any example using Swift Package Manager:\n\n```bash\n# Build all examples\nswift build\n\n# Run a specific example\nswift run HelloWorld\nswift run HelloWorld2\nswift run MultiWindow\nswift run State\nswift run Splashscreen\nswift run Streaming\nswift run RunReturn\n```\n\n\n## Swift Surface Preview\n\n```swift\nlet loop = VeloxRuntimeWry.EventLoop()\nlet proxy = loop?.makeProxy()\nlet window = loop?.makeWindow(configuration: .init(width: 800, height: 600, title: \"Velox\"))\nlet webview = window?.makeWebview(configuration: .init(url: \"https://tauri.app\"))\n\nloop?.pump { event in\n  switch event {\n  case .loopDestroyed, .userExit:\n    return .exit\n  default:\n    return .poll\n  }\n}\n\nproxy?.requestExit()\n```\n\nThis demonstrates the bridging between Swift and the underlying Tao/Wry event loop, window, and\nwebview primitives exposed by the Rust shim. Event callbacks now deliver structured metadata (via\nJSON) which the Swift layer normalises into strongly-typed `VeloxRuntimeWry.Event` values.\n\n### Event Metadata\n\n`VeloxRuntimeWry.Event` exposes rich keyboard, pointer, focus, DPI, and file-drop information so\nSwift applications can respond to Tao/Wry input without having to touch the underlying JSON payloads.\n\n### Window \u0026 Webview Controls\n\nThe Swift API now includes helpers to:\n\n- configure window titles, fullscreen state, sizing constraints, z-order, and visibility;\n- request redraws or reposition windows without touching tao directly;\n- drive Wry webviews via navigation, reload, JavaScript evaluation, zoom control, visibility toggles, and browsing-data clearing.\n- toggle advanced window capabilities including decorations, always-on-bottom/workspace visibility, content protection, focus/focusable state, cursor controls, drag gestures, and attention requests.\n\n### Runtime Lifecycle\n\nVelox now ships a nascent `VeloxRuntime` module that defines the Swift-first protocols mirroring Tauri's runtime traits. `VeloxRuntimeWry.Runtime` remains a stub while the native implementation is completed; the event-loop based APIs remain the primary entry point until the dedicated Swift runtime is feature-complete.\n\n## Examples\n\nThe repository includes several example applications demonstrating Velox capabilities. Examples are located in the `Examples/` directory.\n\n### Running Examples\n\nBuild and run any example using Swift Package Manager:\n\n```bash\n# Build all examples\nswift build\n\n# Run a specific example\nswift run HelloWorld\nswift run HelloWorld2\nswift run MultiWindow\nswift run State\nswift run Splashscreen\nswift run Streaming\nswift run RunReturn\nswift run Commands\nswift run CommandsManual\nswift run CommandsManualRegistry\nswift run Resources\nswift run WindowControls\nswift run MultiWebView\nswift run DynamicHTML\nswift run Events\nswift run Tray\n```\n\n### Asset Loading Approaches\n\nVelox supports two approaches for loading web content, mirroring Tauri's flexibility:\n\n#### 1. Self-Contained (Inline HTML)\n\nThe simplest approach embeds HTML directly in Swift code. This is ideal for simple UIs or when you want a single-binary deployment with no external dependencies.\n\n**Example: HelloWorld**\n\n```swift\nlet html = \"\"\"\n\u003c!doctype html\u003e\n\u003chtml\u003e\n  \u003cbody\u003e\n    \u003ch1\u003eHello from Velox!\u003c/h1\u003e\n  \u003c/body\u003e\n\u003c/html\u003e\n\"\"\"\n\nlet appProtocol = VeloxRuntimeWry.CustomProtocol(scheme: \"app\") { _ in\n  VeloxRuntimeWry.CustomProtocol.Response(\n    status: 200,\n    headers: [\"Content-Type\": \"text/html\"],\n    body: Data(html.utf8)\n  )\n}\n```\n\n**Pros:**\n- Single binary, no external files needed\n- Simple deployment\n- Good for small UIs\n\n**Cons:**\n- HTML/CSS/JS changes require recompilation\n- Less suitable for complex UIs\n- No separation of concerns\n\n#### 2. Bundled Assets (External Files)\n\nFor larger applications, keep HTML, CSS, and JavaScript as separate files loaded at runtime. This mirrors Tauri's asset bundling approach.\n\n**Example: HelloWorld2**\n\n```\nExamples/HelloWorld2/\n├── main.swift          # Swift entry point with AssetBundle\n└── assets/\n    ├── index.html      # HTML markup\n    ├── styles.css      # Stylesheet\n    └── app.js          # JavaScript\n```\n\nThe `AssetBundle` struct discovers and serves files from the assets directory:\n\n```swift\nstruct AssetBundle {\n  let basePath: String\n\n  func loadAsset(path: String) -\u003e (data: Data, mimeType: String)? {\n    // Load file and detect MIME type\n  }\n}\n\nlet appProtocol = VeloxRuntimeWry.CustomProtocol(scheme: \"app\") { request in\n  guard let url = URL(string: request.url),\n        let asset = assets.loadAsset(path: url.path) else {\n    return notFoundResponse()\n  }\n  return VeloxRuntimeWry.CustomProtocol.Response(\n    status: 200,\n    headers: [\"Content-Type\": asset.mimeType],\n    body: asset.data\n  )\n}\n```\n\n**Pros:**\n- Separation of concerns (Swift logic vs web UI)\n- Edit HTML/CSS/JS without recompiling Swift\n- Better for complex UIs and larger teams\n- Familiar web development workflow\n\n**Cons:**\n- Requires bundling assets with the binary\n- Slightly more complex deployment\n\n### Example Overview\n\n| Example | Description | Asset Approach |\n|---------|-------------|----------------|\n| **HelloWorld** | Basic window with inline HTML and IPC | Self-contained |\n| **HelloWorld2** | Same functionality with external assets | Bundled assets |\n| **MultiWindow** | Multiple windows running simultaneously | Self-contained |\n| **State** | Shared state across IPC calls | Self-contained |\n| **Splashscreen** | Splash window before main window | Self-contained |\n| **Streaming** | Server-sent events from Swift to webview | Self-contained |\n| **RunReturn** | Manual event loop control | Self-contained |\n| **Commands** | @VeloxCommand macro for cleanest command definitions | Bundled assets |\n| **CommandsManual** | Manual IPC routing with switch statement | Bundled assets |\n| **CommandsManualRegistry** | Type-safe command DSL with automatic JSON decoding | Bundled assets |\n| **Resources** | Resource bundling and path resolution | Bundled assets |\n| **WindowControls** | Comprehensive window/webview API demonstration | Self-contained |\n| **MultiWebView** | Multiple child webviews: local app + GitHub, tauri.app, Twitter | Mixed |\n| **DynamicHTML** | Swift-rendered dynamic HTML with counter, todos, and themes | Self-contained |\n| **Events** | Event system: backend-to-frontend and frontend-to-backend events | Self-contained |\n| **Tray** | System tray icon with context menu (macOS) | Self-contained |\n\n### Configuration (velox.json)\n\nVelox supports a configuration file (`velox.json`) similar to Tauri's `tauri.conf.json`. This allows declarative app configuration:\n\n```json\n{\n  \"$schema\": \"https://velox.dev/schema/velox.schema.json\",\n  \"productName\": \"MyApp\",\n  \"version\": \"1.0.0\",\n  \"identifier\": \"com.example.myapp\",\n  \"app\": {\n    \"windows\": [\n      {\n        \"label\": \"main\",\n        \"title\": \"My Application\",\n        \"width\": 800,\n        \"height\": 600,\n        \"url\": \"app://localhost/\",\n        \"create\": true,\n        \"visible\": true,\n        \"resizable\": true,\n        \"devtools\": true,\n        \"customProtocols\": [\"app\", \"ipc\"]\n      }\n    ],\n    \"macOS\": {\n      \"activationPolicy\": \"regular\"\n    }\n  },\n  \"build\": {\n    \"frontendDist\": \"assets\"\n  }\n}\n```\n\n**Devtools**: `devtools` defaults to `true` in debug builds and `false` in release. On macOS, enabling devtools uses private WebKit APIs, so avoid setting it to `true` for release builds.\n\nUse `VeloxAppBuilder` to create your app from configuration:\n\n```swift\nimport VeloxRuntime\nimport VeloxRuntimeWry\n\nlet config = try VeloxConfig.load(from: URL(fileURLWithPath: \"path/to/app\"))\nlet eventLoop = VeloxRuntimeWry.EventLoop()!\n\nlet app = VeloxAppBuilder(config: config)\n  .registerProtocol(\"app\") { request in\n    // Serve assets\n  }\n  .registerProtocol(\"ipc\") { request in\n    // Handle IPC commands\n  }\n  .build(eventLoop: eventLoop)\n```\n\n**Platform-Specific Overrides**: Create `velox.macos.json`, `velox.ios.json`, etc. to override settings per platform using RFC 7396 JSON Merge Patch.\n\n### IPC Communication\n\nBoth approaches use custom protocols for IPC between Swift and the webview. Velox injects a\n`window.Velox.invoke` helper that supports both immediate and deferred command responses:\n\n```javascript\n// JavaScript: invoke a Swift command (preferred)\nconst message = await window.Velox.invoke('greet', { name: 'World' });\n```\n\nIf you need a custom helper, you can still use `fetch` for immediate responses:\n\n```javascript\nasync function invoke(command, args = {}) {\n  const response = await fetch(`ipc://localhost/${command}`, {\n    method: 'POST',\n    headers: { 'Content-Type': 'application/json' },\n    body: JSON.stringify(args)\n  });\n  return (await response.json()).result;\n}\n```\n\n#### Deferred Responses\n\nTo return after the IPC handler completes (for modal dialogs or long tasks), defer the response\nand resolve it later. `window.Velox.invoke` will await the final result automatically:\n\n```swift\nstruct DelayedEchoArgs: Codable, Sendable { let message: String; let delayMs: Int? }\n\ncommands.register(\"delayed_echo\", args: DelayedEchoArgs.self, returning: DeferredCommandResponse.self) { args, ctx in\n  let deferred = try ctx.deferResponse()\n  let delay = max(0, args.delayMs ?? 500)\n  DispatchQueue.main.asyncAfter(deadline: .now() + .milliseconds(delay)) {\n    deferred.responder.resolve(args.message)\n  }\n  return deferred.pending\n}\n```\n\n```javascript\nconst reply = await window.Velox.invoke('delayed_echo', { message: 'Hello later', delayMs: 800 });\n```\n\n#### @VeloxCommand Macro (Recommended)\n\nVelox provides the `@VeloxCommand` macro for the cleanest command definitions, similar to Tauri's `#[tauri::command]`:\n\n```swift\nimport VeloxMacros\nimport VeloxRuntimeWry\n\n// Define response types\nstruct GreetResponse: Codable, Sendable {\n  let message: String\n}\n\n// Commands must be in a container (enum/struct) for macro expansion\nenum Commands {\n  @VeloxCommand\n  static func greet(name: String) -\u003e GreetResponse {\n    GreetResponse(message: \"Hello, \\(name)!\")\n  }\n\n  @VeloxCommand\n  static func divide(numerator: Double, denominator: Double) throws -\u003e MathResponse {\n    guard denominator != 0 else {\n      throw CommandError(code: \"DivisionByZero\", message: \"Cannot divide by zero\")\n    }\n    return MathResponse(result: numerator / denominator)\n  }\n\n  // Access state via CommandContext parameter\n  @VeloxCommand\n  static func increment(context: CommandContext) -\u003e CounterResponse {\n    let state: AppState = context.requireState()\n    return CounterResponse(value: state.increment())\n  }\n\n  // Custom command name\n  @VeloxCommand(\"get_counter\")\n  static func getCounter(context: CommandContext) -\u003e CounterResponse {\n    let state: AppState = context.requireState()\n    return CounterResponse(value: state.counter)\n  }\n}\n\n// Register macro-generated commands\nlet registry = commands {\n  Commands.greetCommand      // Generated by @VeloxCommand\n  Commands.divideCommand\n  Commands.incrementCommand\n  Commands.getCounterCommand\n}\n```\n\nSee **Examples/Commands** for a complete demonstration of the `@VeloxCommand` macro.\n\n#### Type-Safe Command DSL\n\nFor cases where you prefer explicit control, use the command DSL directly:\n\n```swift\nimport VeloxRuntime\nimport VeloxRuntimeWry\n\n// Define typed arguments and responses\nstruct GreetArgs: Codable, Sendable {\n  let name: String\n}\n\nstruct GreetResponse: Codable, Sendable {\n  let message: String\n}\n\n// Register commands using the DSL\nlet registry = commands {\n  command(\"greet\", args: GreetArgs.self, returning: GreetResponse.self) { args, _ in\n    GreetResponse(message: \"Hello, \\(args.name)!\")\n  }\n\n  command(\"divide\", args: DivideArgs.self, returning: MathResponse.self) { args, _ in\n    guard args.denominator != 0 else {\n      throw CommandError(code: \"DivisionByZero\", message: \"Cannot divide by zero\")\n    }\n    return MathResponse(result: args.numerator / args.denominator)\n  }\n\n  command(\"increment\", returning: CounterResponse.self) { context in\n    let state: AppState = context.requireState()\n    return CounterResponse(value: state.increment())\n  }\n}\n\n// Create IPC handler and register protocol\nlet stateContainer = StateContainer().manage(AppState())\nlet ipcHandler = createCommandHandler(registry: registry, stateContainer: stateContainer)\nlet ipcProtocol = VeloxRuntimeWry.CustomProtocol(scheme: \"ipc\", handler: ipcHandler)\n```\n\nSee **Examples/CommandsManualRegistry** for a complete demonstration of the type-safe command DSL.\n\n#### Manual IPC Handling\n\nFor simpler cases, you can handle IPC requests manually:\n\n```swift\n// Swift: handle IPC requests manually\nlet ipcProtocol = VeloxRuntimeWry.CustomProtocol(scheme: \"ipc\") { request in\n  let command = URL(string: request.url)?.path.trimmingCharacters(in: .init(charactersIn: \"/\"))\n\n  switch command {\n  case \"greet\":\n    let name = parseArgs(request.body)[\"name\"] as? String ?? \"World\"\n    return jsonResponse([\"result\": \"Hello \\(name)!\"])\n  default:\n    return errorResponse(\"Unknown command\")\n  }\n}\n```\n\n## The Small Print set in H2\n\n### Layout\n\n- `Package.swift`: Swift Package definition exposing the `VeloxRuntimeWry` library target.\n- `Sources/VeloxRuntimeWry`: Swift surface area that mirrors the Tauri runtime concepts with\n  Velox naming.\n- `Sources/VeloxRuntimeWryFFI`: Lightweight C target that bridges into the Rust static library.\n- `runtime-wry-ffi`: Rust crate producing a `velox_runtime_wry_ffi` static/dynamic library that\n  re-exports selected pieces of `tao`, `wry`, and `tauri-runtime-wry`.\n\n### Build Modes\n\nVelox supports two build modes for the Rust FFI crate:\n\n#### Standard Build (crates.io)\n\nUses published versions of `tao` and `wry` from crates.io. This is the default for clean checkouts and CI:\n\n```bash\n# Remove local patches if present\nrm -f .cargo/config.toml\nswift build\n```\n\n#### Local Development Build\n\nUses locally patched `tao` and `wry` with additional testing features. Requires sibling checkouts of these repositories with the `velox-testing` feature added to tao's default features.\n\n```bash\n# Ensure .cargo/config.toml exists with patches (at package root, not runtime-wry-ffi)\n# Then build with local-dev feature:\nVELOX_LOCAL_DEV=1 swift build\n```\n\nThe `.cargo/config.toml` (in the package root) patches crates.io dependencies with local paths:\n```toml\n[patch.crates-io]\ntao = { path = \"../tao\" }\nwry = { path = \"../wry\" }\n```\n\n**Requirements for Local Dev:**\n- Local `tao` version must match crates.io (currently 0.34.5)\n- Local `tao` must have `velox-testing` in its default features in `Cargo.toml`\n- Local `wry` version must match crates.io (currently 0.53.5)\n\n## License\n\nVelox is licensed under either of:\n\n- Apache License, Version 2.0 ([LICENSE-APACHE-2.0](LICENSE-APACHE-2.0) or http://www.apache.org/licenses/LICENSE-2.0)\n- MIT License ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)\n\nat your option.\n\n### Contribution\n\nUnless you explicitly state otherwise, any contribution intentionally submitted for inclusion in Velox by you shall be dual licensed as above, without any additional terms or conditions.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvelox-apps%2Fvelox","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvelox-apps%2Fvelox","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvelox-apps%2Fvelox/lists"}