CryKit

CryKit builds desktop applications with Crystal and HTML/ECR templates. It is the reimagination of Lune, with a focus on writting apps in Crystal + HTML/CSS without having to reach for boilerplate JS glue (for the typical cases at least...) Write state and event handlers in Crystal, style the interface with CSS, and use native windows, dialogs, menus, and trays. Reactive state updates the interface without application JavaScript or a separate frontend build.

CryKit applications currently run on macOS. Linux and Windows application backends lack the native resource loading required at startup.

Status

Experimental/Early development with focus on macOS target for now. If you use this, please anticipate possible API changes between versions.

Prerequisites

• Crystal 1.21.1+, Shards, make, and the native build tools described in Getting started.

Use CryKit in an application

Add CryKit to your application's shard.yml:

dependencies:
  crykit:
    github: AristoRap/crykit

Run shards install, then use require "crykit" in your application. CryKit includes its WebView engine and browser runtime; native code builds automatically during installation and compilation. No separate WebView dependency or Node.js setup is needed.

With the CLI installed, generate and run an application:

crykit init my_app
cd my_app
shards install
crykit dev -w

See the minimal application for a complete counter you can run from a new Crystal project.

Run the demo

From the repository root:

shards install
crystal run src/cli.cr -- dev -w -f examples/demo/crykit.yml

The demo includes a counter, todos with JSON import/export, directory hashing, background streams, and window controls. Explore its source for examples of views, templates, shared state, dialogs, menus, and trays.

dev -w reloads CSS and eligible ECR text/style edits while preserving state; other source changes rebuild and restart the application. Configure watched paths with development.watch in crykit.yml. See development updates.

For a windowless macOS application, run crystal run src/cli.cr -- dev -f examples/tray/crykit.yml. The tray example demonstrates native menus, custom right-click actions, live labels and multiple status items. See the system tray guide for resident lifetime configuration.

For a focused application example, run crystal run src/cli.cr -- dev -f examples/notes/crykit.yml. The Notes example demonstrates editing, debounced model updates, JSON import/export, and native dialogs.

Build an application

Declare assets once with app.assets = CryKit::Assets.directory("assets"). The CLI keeps it on disk for dev and embeds its files in the executable for build:

crystal run src/cli.cr -- build -f examples/demo/crykit.yml --release

The output defaults to bin/<app.name.underscore> beside crykit.yml; use -o PATH to choose another location. The built application serves embedded assets through the same /assets/ URLs and runs without the source asset directory. See assets and CLI configuration.

On macOS, package the Notes example as an application bundle:

crystal run src/cli.cr -- dist -f examples/notes/crykit.yml

This produces examples/notes/dist/Notes.app with embedded assets and release optimizations. Use --skip-release to disable the optimizations. New projects include an editable recipe and plist under targets/. See distribution for configuration, custom templates, and the current ad hoc signing scope. Set app.icon to a square PNG or .icns file to include an application icon.

Documentation

Read the documentation website, or browse the guides in this repository:

• Getting started
• Documentation index
• API reference and CLI commands
• Windows, dialogs, menus, and trays
• Testing applications
• Contributing to CryKit