Plugins

Plugins are Lune's feature modules. Each one maps to a config key in lune.yml, an optional JS namespace in the runtime, and a set of Crystal-side lifecycle phases.

All plugins are active by default. Turn them off individually with disabled:, or whitelist specific ones with enabled::

plugins:
  disabled:
    - tray
    - file_watch

# or whitelist
plugins:
  enabled:
    - system
    - clipboard
    - event
    - stream

---

Core vs standard

Two plugins are marked core: event and stream. They are enabled by default like every other plugin — but disabling them has a cascade effect: any plugin that hard-depends on them is automatically disabled too, with a warning logged at startup.

Type	Can be disabled?	Cascade effect
Core	Yes	All hard-dependents are also disabled
Standard	Yes	No cascade

---

Dependency types

Type	Behaviour
Hard dep	If the dep is inactive, this plugin is automatically disabled (warning logged)
Soft dep	Plugin stays active but a warning is logged; feature degrades gracefully

---

Lifecycle phases

Phase	Interface	When it runs
Bindable	install(ctx)	At startup — registers RPC bridge methods that become the JS namespace
WebviewInject	init_webview(ctx)	At startup — injects JS into the webview (and during build for stubs)
Lifecycle	shutdown	When the window closes — releases OS resources

---

Plugin matrix

Plugin	Config key	JS namespace	Core	Phases	Hard deps	Soft deps	Platforms
Event	event	Event	Yes	WebviewInject	—	—	all
Stream	stream	Stream	Yes	WebviewInject	—	—	all
Clipboard	clipboard	Clipboard	No	Bindable	—	—	all (image: no Win32)
ContextMenu	context_menu	ContextMenu	No	Bindable · WebviewInject	event	—	macOS (Windows/Linux: planned)
DeepLink	deep_link	DeepLink	No	Bindable	event	—	macOS · Linux · Windows²
Dialogs	dialogs	Dialogs	No	Bindable	—	—	all
DragOut	drag_out	DragOut	No	Bindable	—	—	macOS
EditShortcuts	edit_shortcuts	—	No	WebviewInject	—	—	all
FileDrop	file_drop	FileDrop	No	WebviewInject	event	—	macOS · Linux
FileWatch	file_watch	FileWatch	No	Bindable · Lifecycle	event	—	macOS · Linux
Filesystem	filesystem	Filesystem	No	Bindable	—	—	all
Hotkeys	hotkeys	Hotkeys	No	Bindable	—	event	macOS · Linux · Windows
Navigation	navigation	—	No	WebviewInject	—	—	all
Kv	kv	Kv	No	Bindable · Lifecycle	—	—	all
Shell	shell	Shell	No	Bindable · Lifecycle	stream	—	macOS · Linux · Windows³
Sqlite	sqlite	Sqlite	No	Bindable · Lifecycle	—	—	all
System	system	System	No	Bindable	—	—	all (includes screenInfo, notify)
Tray	tray	Tray	No	Bindable	—	event	macOS · Linux¹ · Windows⁴
Window	window	Window	No	Bindable · WebviewInject	—	—	all (chrome opts + drag_zone macOS)
Windows	windows	Windows	No	Bindable · Lifecycle	—	—	all

¹ Requires XWayland on Wayland compositors. ² Windows: cold-start (ARGV) only — no warm-start forwarding yet (Linux has Unix-socket warm-start). ³ Windows: cmd builtins (echo, dir, type, …) and .cmd / .bat shims (npm.cmd, yarn.cmd) are auto-retried via cmd /c when the direct Process.new raises File::NotFoundError — no manual wrapping needed. ⁴ Windows: lune.Tray.setIcon requires a .ico path — PNG / SVG fall back to the system default app icon with a logger warning. opts.tray.toggle_window_on is a no-op (positioning the window relative to the tray icon needs Shell_NotifyIconGetRect plumbing — tracked in ROADMAP.md). Native menus render at the cursor position rather than under the tray icon.

Windows runtime caveat. Every "Windows" entry above is in tree; many are now verified on real hardware. Until Crystal 1.21 ships, building a runnable binary requires the one-line stdlib patch documented in WINDOWS_SETUP.md (crystal#16929, fix in master via crystal#16933). With the patch applied, the runtime works end-to-end. For per-plugin Windows status see the Platform notes section on each plugin page.

---

Dependency graph

Event ──► ContextMenu
         └─► DeepLink
         └─► FileDrop
         └─► FileWatch
         └─► (soft) Tray

Stream   ──► Shell

Disabling event automatically disables ContextMenu, DeepLink, FileDrop, and FileWatch. Disabling stream automatically disables Shell.