Joyride

When developing scripts, you often load namespaces in a REPL. To prevent the main logic of a script from executing every time the file is loaded (which would trigger unwanted side effects), wrap your main entry point in a guard that checks if the file was invoked as a script.

(when (= (joyride/invoked-script) joyride/*file*)
  (main))

You can execute code automatically when Joyride activates by providing activation scripts. These scripts are run in the following order:

1. <User scripts directory>/user_activate.cljs
2. <Workspace scripts directory>/workspace_activate.cljs

Because Joyride uses SCI, you cannot use deftype to implement interfaces. Instead, use a plain JavaScript object (#js) containing the required functions. Use these objects wherever an instance of that interface is expected.

;; Instead of:
;; (deftype Foo [] (bar [x y] ...))

;; Use:
#js {:bar (fn [x y] ...)}

Since Joyride runs in a JS environment, you frequently interact with JS objects and interfaces.

Creating JS Objects: Use the #js literal to create native JavaScript objects. This is required for passing options to VS Code APIs that expect JS objects.

#js {:onClick (fn [event] (println "Clicked!"))}

Destructuring JS Objects: To work with JS objects in a Clojure-idiomatic way, use js->clj with :keywordize-keys true to convert them to Clojure maps.

;; Creating JS objects
#js {:onClick (fn [event] (println "Clicked!"))
     :onHover (fn [event] (println "Hovered!"))}

;; Destructuring JS Objects
(let [{:keys [uri fsPath]} (js->clj workspace-folder :keywordize-keys true)]
  (println "Workspace at:" fsPath))

Joyride searches for your source files in a fixed order of directories. The first match found is used. The search order is:

1. <workspace-root>/.joyride/src
2. <workspace-root>/.joyride/scripts
3. <user-home>/.config/joyride/src
4. <user-home>/.config/joyride/scripts

Joyride automatically discovers scripts based on their location in your file system. Use the following directory structures to organize your scripts:

User Scripts

Store global scripts in your user configuration directory: <user home>/.config/joyride/scripts/**/*.cljs

Workspace Scripts

Store project-specific scripts within your workspace root: .joyride/scripts/**/*.cljs

Joyride uses a central application state and a disposable pattern to manage resources and cleanup.

• Central State: The application state is managed via the !app-db atom, which tracks :disposables, :extension-context, :workspace-root-path, and the :invoked-script.
• Disposables: To prevent resource leaks, use push-disposable! to register cleanup tasks and clear-disposables! to execute them.

;; Central app state
(defonce !app-db (atom {:disposables []
                        :extension-context nil
                        :workspace-root-path nil
                        :invoked-script nil}))

Joyride supports bidirectional communication between your extension logic and the flare's webview.

1. Extension $\rightarrow$ Webview: Use post-message!+ to send a serialized JSON message to a specific flare.
2. Webview $\rightarrow$ Extension: Provide a :message-handler function when calling flare!+. This function will be invoked whenever the webview sends a message.

;; Extension $\rightarrow$ Webview
(post-message!+ :my-flare {:action "update" :data {...}})

;; Webview $\rightarrow$ Extension
(flare!+ {:key :my-flare
          :html "..."
          :message-handler (fn [msg]
                            (js/console.log "Received:" msg))})

Decide where to place your Joyride code based on its scope and intended audience:

Rule of thumb: If it's useful in every workspace, put it in user. If it's project-specific or team-shareable, put it in workspace.