Move text-expander libraries without losing the original
Reversible migration guidance for supported Espanso YAML, AutoHotkey, CSV, TSV, and JSON snippets.
Inventory before converting
Count files, triggers, groups, dynamic variables, scripts, images, rich-text records, application filters, and shared-library dependencies. Mark each item as static text, convertible placeholder, automation, or unknown. Static text is the safest first batch. Unknown and automated entries deserve manual review before any import.
Also identify collisions. The same trigger may exist in multiple source files or already exist in FlitKey. Version 0.5.0 adds imported snippets and does not present a deduplication preview, so importing the same source twice can create duplicates.
Make rollback boring
Copy the entire source configuration rather than only the file you plan to import. Back up FlitKey's config.json as well. Store backups outside the live configuration directories and give them a date and tool version. A rollback should be a file restore, not a reconstruction from memory.
Pause one expander while testing the other. Two active processes listening for the same abbreviation can create duplicate output and make a correct import look broken.
Understand the supported shapes
Espanso YAML support is aimed at static trigger or triggers entries with text replace values and optional labels. Espanso variables, scripts, forms, regex, packages, and application conditions are not converted. AutoHotkey support recognizes supported hotstring and hotkey lines; it is not a general AutoHotkey interpreter.
CSV and TSV can use two columns for trigger and expansion or three for label, trigger, and expansion. JSON must contain recognizable snippet objects. Plain tabular export is useful for data movement, but it discards source-product behavior that has no matching column.
Verify content and behavior separately
First compare the imported label, trigger, and expansion with the source. Then test runtime behavior in a disposable editor. Include Unicode, newlines, punctuation, placeholders, and cursor placement. Finally test the real applications that matter. A correct record can still behave differently when an application handles synthetic input, clipboard paste, or elevated privileges differently.
On Wayland, do not use typed expansion as the acceptance test for FlitKey 0.5.0. Open Quick Insert, choose the rendered snippet, and paste it. The platform workflow is different even when the stored record is correct.
Know when not to migrate
Stay with Espanso if regex, forms, scripts, packages, and version-controlled YAML are central to the library. Keep AutoHotkey for window automation, remapping, and conditional Windows logic. Keep a commercial product when shared libraries, permissions, vendor support, mobile access, or rich content are requirements.
A partial migration is valid. FlitKey can own simple reusable text while another tool retains advanced automation, provided triggers do not conflict and the security implications of running both are acceptable.