Coruscation.net

About Dynamic Adding to Classpath in Clojure

2026-01-25T00:00:00+08:00

Well, I guess people will just inevitably get into the problem of classpath, one way or another. The Classpath is a Lie described the problem very well: classpath is a lie. classpath, per se, is a simple list separated by colons, however, the real work is done by the Classloader.

Nevertheless, this isn't a post talking about classpath and ClassLoader. There are already a lot of great articles talking about it (links at the end of this post), and I can't claim I understand ClassLoaders to the extent that I can confidently teach others about it either.

This is a blog about what I have found during the process of trying to add new directories to classpath and require Clojure files in them at runtime. ClassLoader in Clojure is something very messy. The best strategy probably is to avoid the problem altogether. But still, if you really want to do it, I wish the following content can offer some help.

Use Builtin `clojure.core/add-classpath`

Clojure has a builtin add-classpath function. Although it has been deprecated, it works for simple use cases.

(defn check-dynamic-load []
  (let [tmp-dir (.toFile (Files/createTempDirectory "classpath-demo" (into-array java.nio.file.attribute.FileAttribute [])))
        tmp-clj (File/createTempFile "demo" ".clj" tmp-dir)
        tmp-name (subs (.getName tmp-clj)
                       0
                       (.lastIndexOf (.getName tmp-clj)
                                     "."))]
    ;; Add `tmp-dir` to `classpath` using builtin `add-classpath`.
    (add-classpath (.toURL tmp-dir))

    ;; Put a Clojure file under the directory
    (spit tmp-clj
          (str "(ns " tmp-name ") (def a 1)"))
                                        ;
    ;; `require` the Clojure file, and resolve the variable
    (assert (= 1 (var-get (requiring-resolve (symbol tmp-name
                                                     "a")))))

    ;; Update the Clojure file
    (spit tmp-clj
          (str "(ns " tmp-name ") (def a 2)"))

    ;; Reload the Clojure file
    (require (symbol tmp-name)
             :reload-all)

    ;; We can read the new value
    (assert (= 2 (var-get (requiring-resolve (symbol tmp-name
                                                     "a")))))
    (println "success")))

;; success
(check-dynamic-load)

If we evaluate the above code in a REPL or in cider, it works and prints "success". As we can see from the code, we can require a Clojure file whose path determined at runtime, and reload it to get the updated value.

However, there is a reason of it being deprecated. We can check its source code:

// The method used by clojure.core/add-classpath
static public void addURL(Object url) throws MalformedURLException{
      URL u = (url instanceof String) ? toUrl((String) url) : (URL) url;
      ClassLoader ccl = Thread.currentThread().getContextClassLoader();
      if(ccl instanceof DynamicClassLoader)
              ((DynamicClassLoader)ccl).addURL(u);
      else
              throw new IllegalAccessError("Context classloader is not a DynamicClassLoader");
}

It checks if the current thread's ContextClassLoader is a DynamicClassLoader. If so, it will call the DynamicClassLoader's addURL method. That means, this method will fail if there's some code set the current ContextClassLoader to something other than a DynamicClassLoader.

We expect add-classpath continues to work in case because the convention of setting a new ClassLoader is to set the current ClassLoader as the parent of the newly created ClassLoader. However, clojure.core/add-classpath only checks the current ClassLoader, more on this in the section.

(let [future
      (future
        (let [cl (.getContextClassLoader (Thread/currentThread))]
          (.setContextClassLoader (Thread/currentThread)
                                  (java.net.URLClassLoader. (into-array java.net.URL [])
                                                            cl)))
            (try (check-dynamic-load)
             (assert "unreachable")
             (catch Throwable t
               (println "dynamic loading failed"))))]
  ;; "dynamic loading failed"
  @future)

Use `add-classpath` from `pomegranate`

pomegranate provides a add-classpath that solves the problem described in the previous section.

The only thing we need to change is to replace clojure.core/add-classpath with cemerick.pomegranate/add-classpath.

(ns demo
  (:require
   [cemerick.pomegranate :as pomegranate]))

(defn check-dynamic-load-using-pomegranate []
  (let [;; ...
        ]
    ;; same code as `check-dynamic-load`
    (pomegranate/add-classpath (.toURL tmp-dir))
    ;; same code as `check-dynamic-load`
    ))

(let [future
      (future
        (let [cl (.getContextClassLoader (Thread/currentThread))]
          (.setContextClassLoader (Thread/currentThread)
                                  (java.net.URLClassLoader. (into-array java.net.URL [])
                                                            cl)))
        (check-dynamic-load-using-pomegranate)
        (print "success"))]
  ;; success
  @future)

Unlike add-classpath from clojure.core, pomegranate's add-classpath try to find the ClassLoader closest to the Primordial ClassLoader that is compatible with add-classpath, and call the addURL method from it.

;; in `add-classpath` function in pomegranate.clj  
(let [classloaders (classloader-hierarchy)]
      (if-let [cl (last (filter modifiable-classloader? classloaders))]
        (add-classpath jar-or-dir cl)
        (throw (IllegalStateException. (str "Could not find a suitable classloader to modify from "
                                            (mapv (fn [^ClassLoader c]
                                                    (-> c .getClass .getSimpleName))
                                                  classloaders))))))

Create a `DynamicClassLoader` When There isn't One

If you are running Clojure in REPL or with nrepl, the ContextClassLoader of the current thread will certainly be DynamicClassLoader, set by one of those tools. However, when you run clj command in a non-interactive manner, or use a AOT-compiled jar file, this wouldn't be the case.

This problem is quite easy to solve, we just need to set the ContextClassLoader to a DynamicClassLoader created by ourselves in the entrypoint of the program.

(defn -main [& args]
  (let [cl (.getContextClassLoader (Thread/currentThread))]
    (.setContextClassLoader (Thread/currentThread) (clojure.lang.DynamicClassLoader. cl)))
  ;; other code...
  )

When Using `kaocha`

So far, so good. Except when you finish the code and try to test some code and run it under the kaocha test runner. kaocha also did its own thing with ClassLoader and provides a add-classpath method. It breaks the previous method.

By detecting kaocha's presence and calling its add-classpath, alongside with the pomegranate one solves the issue for me.

(when (find-ns 'kaocha.classpath)
  ((intern 'kaocha.classpath
           'add-classpath)
   new-path))

Pitfall When Using a Threadpool

When you create a thread, the new thread will inherit the ContextClassLoader of the thread created it. However when you explicitly or implicitly (like when using future) use a threadpool, the executor may choose an existing thread, which could have a ContextClassLoader different from the calling thread.

You may consider creating a thread directly instead of relying on future in this case.

(doto (Thread/new
       (bound-fn []
         ;; code
         ))
  (.start))

A Few More Words

This post is definitely not comprehensive, and there are still a lot things I currently do not understand. The method I have described works for me for now. If you want to understand more about this topic, I have listed a few links below.

Something Like MDX but with Clojure and Org-Mode for My Personal Blog: Part I

2026-01-03T01:47:09+08:00

MDX is a tool lets you write JavaScript and JSX in a Markdown file. It will then compile the Markdown file into a JavaScript file, so that we can use it from other JavaScript code. I always wanted something similar for my personal blog. For some background, the blogging program is written in Clojure/ClojureScript. The blogging program runs on the JVM, it works by statically generating all the HTML and other files so that the result could be hosted on platforms like Github Pages. Posts of my blog are written in org-mode. As the blog program runs on the JVM, directly using MDX is theoratically possible, but probably would create a lot of frictions.

Therefore I took some time to implement something similar. Albeit it is not fully tested, the result is quite satisfactory: I can embed Clojure code directly in an Org file, or use React components defined in Clojure code with native Org syntax. The Org file can then be converted into a Cljc file and used from other Clojure code.

In the following sections I will call it OrgX.

This is part one of the series, in this post I will show the features and in the next post I will describe the process of implementing it

How OrgX Works

Similar to MDX, OrgX works by compiling the OrgX file into a Cljc file. A basic OrgX file would look like this:

example.org:

#+ORGX: true

/*Hello* from @@orgx:($ :span "OrgX")@@/

#+begin_orgx
($ :div (str "Hello" " World!"))
#+end_orgx

It will be converted into something similar to the following Clojure snippet.

orgx/example.cljc:

(ns orgx.example
  (:require [uix.core :as uix :refer
             [defui use-state use-effect use-context $]]))

(defui _comp [post-props]
  ($ :<>
     ($ :p {} ($ :i {}
                 ($ :b {} "Hello")
                 " from "
                 ($ :span "OrgX")))
     ($ :div (str "Hello" " World!"))))

(defui component [props]
  ($ _comp (merge (quote {#_"default properties"}) props)))

The blogging program uses uix as its React wrapper, thus the generated Clojure code is using uix. Some uix functions like $ are also imported by default.

As you can see from this example:

We can @@orgx:@@ for inline Clojure code and #+begin_orgx for Clojure blocks.
The embedded Clojure code are put in a component called _comp, along with other contents in the Org file.
The outer component wraps the _comp component, its provides some metadata about this post related to the blogging program. More about this on the following sections.
We can use the component component from other Clojure code.

Basic Usage

As we have seen from the earily example, #+begin_orgx and @@orgx:@@ are the most basic structure for standalone and inline Clojure code, respectively.

We can have a clickable button with the following code.

#+begin_orgx
  ;; you can style it using tailwindcss
  ($ :button {:class "bg-sky-600 text-neutral-50 py-1 px-2 rounded-lg"
     :on-click (fn [& _]
                   #?(:cljs (js/alert "clicked!")))}
  "click me")
#+end_orgx

That will be rendered as:

Notice the reader conditional macro #?(:cljs) . The generated Clojure code is in a Cljc file, therefore it pairs well with the server side rendering or static generation. However, it also means we need to put the platform specified code in the corresponding reader conditionals.

We can also use the button inline this way: @@orgx:($ :button {:class "bg-sky-600 text-neutral-50 py-1 px-2 rounded-lg" :on-click (fn [& _] #?(:cljs (js/alert "clicked!")))} "Click Me")@@

The above snippet will be rendered as:

We can also use the button inline this way:

Toplevel Clojure Code

You may have noticed that, all the Clojure code being put in a component means that we can't use Clojure code that only works on the top level like defn or require. To solve this, we can use #+attr_orgx_toplevel: true to mark a OrgX block and make its contents appear in toplevel of the generated Clojure file.

Let's go back to the button example, we can define a my-button component with the following code:

#+attr_orgx_toplevel: true
#+begin_orgx
(defui my-button [{:keys [children callback]}]
    ($ :button {:class "bg-sky-600 text-neutral-50 py-1 px-2 rounded-lg"
       :on-click (fn [& _]
                   (if callback (callback)))}
    children))
#+end_orgx

The defui will be put on the top level in the generated Clojure code, along side something like _comp:

(ns ...)
(defui my-button [{:keys [children callback]}]
  ($ :button {:class "bg-sky-600 text-neutral-50 py-1 px-2 rounded-lg"
              :on-click (fn [& _]
                          #?(:cljs (callback)))}
     children))

(defui _comp ...)

We can then easily use the my-button component with either inline or standalone OrgX block.

Example Usage:

Inline OrgX block:
@@orgx:($ my-button {:callback (fn [] #?(:cljs (js/alert "Hello From inline OrgX")))} "From inline OrgX")@@
#+begin_orgx
($ :div "We can also use it in a orgx block"
    ($ my-button {:callback (fn [] #?(:cljs (js/alert "Hello from OrgX block!")))}
         "From OrgX block"))
#+end_orgx

Rendering:

Inline OrgX block:

We can also use it in a orgx block

Import Modules

In MDX, we can import modules with normal import statements. In OrgX, we can do something similar with toplevel OrgX block and the require function.

#+attr_orgx_toplevel: true
#+begin_orgx
(require '[clojure.string :as string])
#+end_orgx

We can also do this with keyword metadata at the beginning of an Org file.

#+ORGX_REQUIRE: [[clojure.string :as string]]

Settings in keyword metadata currently doesn't support reader macros.

Access Component Properties

Similar to MDX, we can access the component's properties with the post-props variable. Some metadata are also provided in the post-props variable.

The following metadata are provided by default:

Example:

($ :pre
  (binding [*print-namespace-maps* true]
    (with-out-str (pprint/pprint post-props))))

Result:

#:blog{:orgx true,
       :tags [],
       :unlisted false,
       :title
       "Something Like MDX but with Clojure and Org-Mode for My Personal Blog: Part I",
       :show-toc? true,
       :file-path
       "/home/void/Projects/cerulean/workspace/blogs/some-like-mdx-but-with-clojure-and-org-mode.org",
       :author nil,
       :email nil,
       :description
       "MDX  is a tool lets you write JavaScript and JSX in a Markdown file. It will then compile the Markdown file into a JavaScript file, so that we can use it f...",
       :id
       "something-like-mdx-but-with-clojure-and-org-mode-for-my-personal-blog--part-i",
       :category "Coding",
       :language "en_US",
       :published-date "2026-01-03T01:47:09+08:00",
       :content
       "<p>\n<a href=\"https://mdxjs.com/\">MDX</a> is a tool lets you write JavaScript and JSX in a Markdown file. It will then compile the Markdown file into a JavaScript file, so that we can use it from other JavaScript code. I always wanted something similar for my personal blog. For some background, the blogging program is written in Clojure/ClojureScript. The blogging program runs on the JVM, it works by statically generating all the HTML and other files so that the result could be hosted on platforms like Github Pages. Posts of my blog are written in <a href=\"https://orgmode.org\">org-mode</a>. As the blog program runs on the JVM, directly using MDX is theoratically possible, but probably would create a lot of frictions.\n</p>\n\n<p>\nTherefore I took some time to implement something similar. Albeit it is not fully tested, the result is quite satisfactory: I can embed Clojure code directly in an Org file, or use React components defined in Clojure code with native Org syntax. The Org file can then be converted into a Cljc file and used from other Clojure code.\n</p>\n\n<p>\nIn the following sections I will call it <code>OrgX</code>.\n</p>\n\n<pre class=\"orgx\" data-wrapper=\"use-comp\" data-wrapper-data=\"info\"><p>\n<i>This is part <b>one</b> of the series, in this post I will show the features and in the next post I will describe the process of implementing it</i>\n</p>\n\n</pre>\n<div id=\"outline-container-how-orgx-works\" class=\"outline-2\">\n<a href=\"#how-orgx-works\"><h2 id=\"how-orgx-works\" class=\"cr-self-reference \">How OrgX Works</h2></a>\n<div class=\"outline-text-2\" id=\"text-how-orgx-works\">\n<p>\nSimilar to MDX, OrgX works by compiling the OrgX file into a <a href=\"https://clojure.org/guides/reader_conditionals\">Cljc</a> file. A basic OrgX file would look like this:\n</p>\n\n<pre class=\"orgx\" data-wrapper=\"use-defui\" data-wrapper-data=\"orgx-example\"><pre class=\"example\" id=\"orgc3c59e4\">#+ORGX: true\n\n/*Hello* from @@orgx:($ :span &quot;OrgX&quot;)@@/\n\n#+begin_orgx\n($ :div (str &quot;Hello&quot; &quot; World!&quot;))\n#+end_orgx\n</pre>\n\n</pre>\n\n\n<pre class=\"orgx\">($ tabs {:tab-list [{:name &quot;example.org&quot; :content ($ orgx-example)}]})\n\n</pre>\n\n\n<p>\nIt will be converted into something similar to the following Clojure snippet.\n</p>\n\n<pre class=\"orgx\" data-wrapper=\"use-defui\" data-wrapper-data=\"orgx-cljc\"><div class=\"org-src-container\">\n<pre class=\"cr-highlighted\"><code class=\"lang-clojure\"><html><head></head><body>(<span class=\"hljs-name\"><span class=\"hljs-built_in\">ns</span></span> orgx.example\n  (<span class=\"hljs-symbol\">:require</span> [uix.core <span class=\"hljs-symbol\">:as</span> uix <span class=\"hljs-symbol\">:refer</span>\n             [defui use-state use-effect use-context $]]))\n\n(<span class=\"hljs-name\">defui</span> _comp [post-props]\n  ($ <span class=\"hljs-symbol\">:&lt;&gt;</span>\n     ($ <span class=\"hljs-symbol\">:p</span> {} ($ <span class=\"hljs-symbol\">:i</span> {}\n                 ($ <span class=\"hljs-symbol\">:b</span> {} <span class=\"hljs-string\">&quot;Hello&quot;</span>)\n                 <span class=\"hljs-string\">&quot; from &quot;</span>\n                 ($ <span class=\"hljs-symbol\">:span</span> <span class=\"hljs-string\">&quot;OrgX&quot;</span>)))\n     ($ <span class=\"hljs-symbol\">:div</span> (<span class=\"hljs-name\"><span class=\"hljs-built_in\">str</span></span> <span class=\"hljs-string\">&quot;Hello&quot;</span> <span class=\"hljs-string\">&quot; World!&quot;</span>))))\n\n(<span class=\"hljs-name\">defui</span> component [props]\n  ($ _comp (<span class=\"hljs-name\"><span class=\"hljs-built_in\">merge</span></span> (<span class=\"hljs-name\"><span class=\"hljs-built_in\">quote</span></span> {#_<span class=\"hljs-string\">&quot;default properties&quot;</span>}) props)))\n</body></html></code></pre>\n</div>\n\n</pre>\n\n<pre class=\"orgx\">($ tabs {:tab-list [{:name &quot;orgx/example.cljc&quot; :content ($ orgx-cljc)}]})\n\n</pre>\n\n<pre class=\"orgx\" data-wrapper=\"use-comp\" data-wrapper-data=\"note\"><p>\nThe blogging program uses <a href=\"https://github.com/pitch-io/uix?tab=readme-ov-file\">uix</a> as its React wrapper, thus the generated Clojure code is using uix. Some uix functions like <code>$</code> are also imported by default. \n</p>\n\n</pre>\n\n<p>\nAs you can see from this example:\n</p>\n\n<ul class=\"org-ul\">\n<li>We can <code>@@orgx:@@</code> for inline Clojure code and <code>#+begin_orgx</code> for Clojure blocks.</li>\n<li>The embedded Clojure code are put in a component called <code>_comp</code>, along with other contents in the Org file.</li>\n<li>The outer <code>component</code> wraps the <code>_comp</code> component, its provides some metadata about this post related to the blogging program. More about this on the following sections.</li>\n<li>We can use the <code>component</code> component from other Clojure code.</li>\n</ul>\n</div>\n</div>\n<div id=\"outline-container-basic-usage\" class=\"outline-2\">\n<a href=\"#basic-usage\"><h2 id=\"basic-usage\" class=\"cr-self-reference \">Basic Usage</h2></a>\n<div class=\"outline-text-2\" id=\"text-basic-usage\">\n<p>\nAs we have seen from the earily example, <code>#+begin_orgx</code> and <code>@@orgx:@@</code> are the most basic structure for standalone and inline Clojure code, respectively.\n</p>\n\n<p>\nWe can have a clickable button with the following code.\n</p>\n\n<pre class=\"example\" id=\"orgb18a8ba\">#+begin_orgx\n  ;; you can style it using tailwindcss\n  ($ :button {:class &quot;bg-sky-600 text-neutral-50 py-1 px-2 rounded-lg&quot;\n     :on-click (fn [&amp; _]\n                   #?(:cljs (js/alert &quot;clicked!&quot;)))}\n  &quot;click me&quot;)\n#+end_orgx\n</pre>\n\n<p>\nThat will be rendered as:\n</p>\n\n<pre class=\"orgx\">  ($ :button {:class &quot;my-2 bg-sky-600 text-neutral-50 py-1 px-2 rounded-lg&quot; :on-click (fn [&amp; _] #?(:cljs (js/alert &quot;clicked!&quot;)))} &quot;Click Me&quot;)\n\n</pre>\n\n<p>\nNotice the <a href=\"https://clojure.org/guides/reader_conditionals\">reader conditional macro</a> <code>#?(:cljs)</code>  . The generated Clojure code is in a Cljc file, therefore it pairs well with the server side rendering or static generation. However, it also means we need to put the platform specified code in the corresponding reader conditionals.\n</p>\n\n<pre class=\"example\" id=\"orge805190\">We can also use the button inline this way: @@orgx:($ :button {:class &quot;bg-sky-600 text-neutral-50 py-1 px-2 rounded-lg&quot; :on-click (fn [&amp; _] #?(:cljs (js/alert &quot;clicked!&quot;)))} &quot;Click Me&quot;)@@\n</pre>\n\n<p>\nThe above snippet will be rendered as:\n</p>\n\n<p>\nWe can also use the button inline this way: <code class=\"orgx\">\n($ :button {:class &quot;bg-sky-600 text-neutral-50 py-1 px-2 rounded-lg&quot; :on-click (fn [&amp; _] #?(:cljs (js/alert &quot;clicked!&quot;)))} &quot;Click Me&quot;)\n</code>\n</p>\n</div>\n<div id=\"outline-container-toplevel-clojure-code\" class=\"outline-3\">\n<a href=\"#toplevel-clojure-code\"><h3 id=\"toplevel-clojure-code\" class=\"cr-self-reference \">Toplevel Clojure Code</h3></a>\n<div class=\"outline-text-3\" id=\"text-toplevel-clojure-code\">\n<p>\nYou may have noticed that, all the Clojure code being put in a component means that we can't use Clojure code that only works on the top level like <code>defn</code> or <code>require</code>. To solve this, we can use <code>#+attr_orgx_toplevel: true</code> to mark a OrgX block and make its contents appear in toplevel of the generated Clojure file.\n</p>\n\n<p>\nLet's go back to the button example, we can define a <code>my-button</code> component with the following code:\n</p>\n\n<pre class=\"example\" id=\"orgb24feeb\">#+attr_orgx_toplevel: true\n#+begin_orgx\n(defui my-button [{:keys [children callback]}]\n    ($ :button {:class &quot;bg-sky-600 text-neutral-50 py-1 px-2 rounded-lg&quot;\n       :on-click (fn [&amp; _]\n                   (if callback (callback)))}\n    children))\n#+end_orgx\n</pre>\n\n<pre class=\"orgx\" data-toplevel=\"\">  (defui my-button [{:keys [children callback]}]\n      ($ :button {:class &quot;bg-sky-600 text-neutral-50 py-1 px-2 rounded-lg&quot;\n         :on-click (fn [&amp; _]\n                     (if callback (callback)))}\n      children))\n\n</pre>\n\n<p>\nThe <code>defui</code> will be put on the top level in the generated Clojure code, along side something like <code>_comp</code>:\n</p>\n\n<div class=\"org-src-container\">\n<pre class=\"cr-highlighted\"><code class=\"lang-clojure\"><html><head></head><body>(<span class=\"hljs-name\"><span class=\"hljs-built_in\">ns</span></span> ...)\n(<span class=\"hljs-name\">defui</span> my-button [{<span class=\"hljs-symbol\">:keys</span> [children callback]}]\n  ($ <span class=\"hljs-symbol\">:button</span> {<span class=\"hljs-symbol\">:class</span> <span class=\"hljs-string\">&quot;bg-sky-600 text-neutral-50 py-1 px-2 rounded-lg&quot;</span>\n              <span class=\"hljs-symbol\">:on-click</span> (<span class=\"hljs-name\"><span class=\"hljs-built_in\">fn</span></span> [&amp; _]\n                          #?(<span class=\"hljs-symbol\">:cljs</span> (<span class=\"hljs-name\">callback</span>)))}\n     children))\n\n(<span class=\"hljs-name\">defui</span> _comp ...)\n</body></html></code></pre>\n</div>\n\n<p>\nWe can then easily use the <code>my-button</code> component with either inline or standalone OrgX block.\n</p>\n\n<pre class=\"orgx\" data-wrapper=\"use-defui\" data-wrapper-data=\"mybutton_example\"><pre class=\"example\" id=\"orgc3ab17f\">Inline OrgX block:\n@@orgx:($ my-button {:callback (fn [] #?(:cljs (js/alert &quot;Hello From inline OrgX&quot;)))} &quot;From inline OrgX&quot;)@@\n#+begin_orgx\n($ :div &quot;We can also use it in a orgx block&quot;\n    ($ my-button {:callback (fn [] #?(:cljs (js/alert &quot;Hello from OrgX block!&quot;)))}\n         &quot;From OrgX block&quot;))\n#+end_orgx\n</pre>\n\n</pre>\n\n<pre class=\"orgx\" data-wrapper=\"use-defui\" data-wrapper-data=\"mybutton_result\"><p>\nInline OrgX block:\n<code class=\"orgx\">\n($ my-button {:callback (fn [] #?(:cljs (js/alert &quot;Hello From inline OrgX&quot;)))} &quot;From inline OrgX&quot;)\n</code>\n</p>\n<pre class=\"orgx\">($ :div &quot;We can also use it in a orgx block&quot;\n    ($ my-button {:callback (fn [] #?(:cljs (js/alert &quot;Hello from OrgX block!&quot;)))}\n         &quot;From OrgX block&quot;))\n\n</pre>\n\n</pre>\n\n<pre class=\"orgx\">($ showcase {:showcase-name &quot;Rendering&quot;}\n  ($ tabs {:tab-list [{:name &quot;Example Usage&quot; :content ($ mybutton_example)}]})\n  ($ mybutton_result))\n\n</pre>\n</div>\n</div>\n<div id=\"outline-container-import-modules\" class=\"outline-3\">\n<a href=\"#import-modules\"><h3 id=\"import-modules\" class=\"cr-self-reference \">Import Modules</h3></a>\n<div class=\"outline-text-3\" id=\"text-import-modules\">\n<p>\nIn MDX, we can import modules with normal <code>import</code> statements. In OrgX, we can do something similar with toplevel OrgX block and the <code>require</code> function.\n</p>\n\n<pre class=\"example\" id=\"orga8b559a\">#+attr_orgx_toplevel: true\n#+begin_orgx\n(require '[clojure.string :as string])\n#+end_orgx\n</pre>\n\n<p>\nWe can also do this with keyword metadata at the beginning of an Org file.\n</p>\n\n<pre class=\"example\" id=\"orgc2e9035\">#+ORGX_REQUIRE: [[clojure.string :as string]]\n</pre>\n\n<pre class=\"orgx\" data-wrapper=\"use-comp\" data-wrapper-data=\"note\"><p>\nSettings in keyword metadata currently doesn't support reader macros.\n</p>\n\n</pre>\n</div>\n</div>\n<div id=\"outline-container-access-component-properties\" class=\"outline-3\">\n<a href=\"#access-component-properties\"><h3 id=\"access-component-properties\" class=\"cr-self-reference \">Access Component Properties</h3></a>\n<div class=\"outline-text-3\" id=\"text-access-component-properties\">\n<p>\nSimilar to MDX, we can access the component's properties with the <code>post-props</code> variable. Some metadata are also provided in the <code>post-props</code> variable.\n</p>\n\n<pre class=\"orgx\" data-wrapper=\"use-defui\" data-wrapper-data=\"metadata-example\"><pre class=\"example\" id=\"orgbd2cae9\">($ :pre\n  (binding [*print-namespace-maps* true]\n    (with-out-str (pprint/pprint post-props))))\n</pre>\n\n</pre>\n\n<p>\nThe following metadata are provided by default:\n</p>\n\n<pre class=\"orgx\">($ showcase ($ tabs {:tab-list [{:name &quot;Example&quot; :content ($ metadata-example)}]}) ($ :pre (binding [*print-namespace-maps* true] (with-out-str (pprint/pprint post-props)))))\n\n</pre>\n</div>\n</div>\n<div id=\"outline-container-use-other-orgx-files-as-components\" class=\"outline-3\">\n<a href=\"#use-other-orgx-files-as-components\"><h3 id=\"use-other-orgx-files-as-components\" class=\"cr-self-reference \">Use Other OrgX Files as Components</h3></a>\n<div class=\"outline-text-3\" id=\"text-use-other-orgx-files-as-components\">\n<p>\nBy default, OrgX files are compiled as Cljc files and will be put in the <code>orgx</code> namespace. You can import them as described in <a href=\"#import-modules\">Import Modules</a>.\n</p>\n</div>\n</div>\n</div>\n<div id=\"outline-container-use-orgx-with-native-org-syntax\" class=\"outline-2\">\n<a href=\"#use-orgx-with-native-org-syntax\"><h2 id=\"use-orgx-with-native-org-syntax\" class=\"cr-self-reference \">Use OrgX With Native Org Syntax</h2></a>\n<div class=\"outline-text-2\" id=\"text-use-orgx-with-native-org-syntax\">\n</div>\n<div id=\"outline-container-use-components\" class=\"outline-3\">\n<a href=\"#use-components\"><h3 id=\"use-components\" class=\"cr-self-reference \">Use Components</h3></a>\n<div class=\"outline-text-3\" id=\"text-use-components\">\n<p>\nWriting <code>#+begin_orgx</code> and Clojure code must be very tedious every time we want to use a simple component, like <code>note</code> or <code>warning</code> notice blocks.\n</p>\n\n<p>\nTo solve this problem, a new syntax <code>#+orgx_{comp-name}</code> has been introduced.\n</p>\n\n<p>\nFor example:\n</p>\n\n<pre class=\"orgx\" data-wrapper=\"use-defui\" data-wrapper-data=\"orgx_syntax_example\"><pre class=\"example\" id=\"orgff794f0\">#+begin_orgx_note\nThis is a note\n\n+ /Normal/ Org markups *can* be used inside it\n\n@@orgx:($ :span &quot;You can even nest OrgX syntax in it&quot;)@@\n#+end_orgx_note\n</pre>\n\n</pre>\n\n<pre class=\"orgx\" data-wrapper=\"use-defui\" data-wrapper-data=\"orgx_syntax_result\"><pre class=\"orgx\" data-wrapper=\"use-comp\" data-wrapper-data=\"note\"><p>\nThis is a note\n</p>\n\n<ul class=\"org-ul\">\n<li><i>Normal</i> Org markups <b>can</b> be used inside it</li>\n</ul>\n\n<p>\n<code class=\"orgx\">\n($ :span &quot;You can even nest OrgX syntax in it&quot;)\n</code>\n</p>\n\n</pre>\n\n</pre>\n\n<pre class=\"orgx\">($ showcase {:showcase-name &quot;Rendering&quot;}\n  ($ tabs {:tab-list [{:name &quot;Use Component With Org Syntax&quot; :content ($  orgx_syntax_example)}]})\n  ($ orgx_syntax_result))\n\n</pre>\n\n<p>\nIt works by passing the rendered content to the component <code>note</code> as <code>children</code>. All other Org markups or structures that can be used in an Org environment can also be used here. You can also nested other OrgX structures in it, except for top level Clojure definition and component building, which are not supported.\n</p>\n\n<pre class=\"orgx\" data-wrapper=\"use-comp\" data-wrapper-data=\"note\"><p>\nCurrently we can't pass other properties to the component using this syntax, but that might change in the future.\n</p>\n\n</pre>\n</div>\n</div>\n<div id=\"outline-container-build-components\" class=\"outline-3\">\n<a href=\"#build-components\"><h3 id=\"build-components\" class=\"cr-self-reference \">Build Components</h3></a>\n<div class=\"outline-text-3\" id=\"text-build-components\">\n<p>\nSomething we may want to build a React component out of some Org blocks. Like we may want to pass two Org mode source blocks as arguments to a <code>tabs</code> components.\nTo do this, we just need to add an annotation to the existing <code>#+begin_orgx_{comp-name}</code> syntax:\n</p>\n\n<pre class=\"example\" id=\"org78eb610\">#+attr_orgx_defui: true\n#+begin_orgx_my-note\n*@@orgx:(or (:note-text props) &quot;Tip&quot;)@@*\n#+begin_orgx\n(:children props)\n#+end_orgx\n#+end_orgx_my-note\n</pre>\n\n<pre class=\"orgx\" data-wrapper=\"use-defui\" data-wrapper-data=\"my-note\"><p>\n<b><code class=\"orgx\">\n(or (:note-text props) &quot;Tip&quot;)\n</code></b>\n</p>\n<pre class=\"orgx\">(:children props)\n\n</pre>\n\n</pre>\n\n\n<p>\nAs shown in the example, we can use normal Org syntax along with OrgX snippets. We can also access the properties with the <code>props</code> variable.\n</p>\n\n<p>\nIn the above example we have defined a <code>my-note</code> component, we can then use it with any aforementioned methods.\n</p>\n\n<pre class=\"orgx\" data-wrapper=\"use-defui\" data-wrapper-data=\"my-note-example\"><pre class=\"example\" id=\"org54e2523\">#+begin_orgx_my-note\nThis is a note!\n#+end_orgx_my-note\n</pre>\n\n</pre>\n\n<pre class=\"orgx\" data-wrapper=\"use-defui\" data-wrapper-data=\"my-note-result\"><pre class=\"orgx\" data-wrapper=\"use-comp\" data-wrapper-data=\"my-note\"><p>\nThis is a note!\n</p>\n\n</pre>\n\n</pre>\n\n<pre class=\"orgx\">($ showcase {:showcase-name &quot;Rendering&quot;}\n  ($ tabs {:tab-list [{:name &quot;Example Usage&quot; :content ($ my-note-example)}]})\n  ($ my-note-result))\n\n</pre>\n</div>\n</div>\n<div id=\"outline-container-inline-orgx-with-macros\" class=\"outline-3\">\n<a href=\"#inline-orgx-with-macros\"><h3 id=\"inline-orgx-with-macros\" class=\"cr-self-reference \">Inline OrgX with Macros</h3></a>\n<div class=\"outline-text-3\" id=\"text-inline-orgx-with-macros\">\n<p>\nCurrently no similar syntax for inline OrgX is supported, however, it is fairly easy to make life easier with macros. Let's go back to use <code>my-button</code> as the example.\n</p>\n\n<pre class=\"orgx\" data-wrapper=\"use-defui\" data-wrapper-data=\"macro-example\"><p>\nWe can define a macro like:\n</p>\n<pre class=\"example\" id=\"org2cb14d6\">#+MACRO: my-button @@orgx:($ my-button {:callback (or $2 nil)} $1)@@\n</pre>\n\n\n<p>\nAnd then use it with:\n</p>\n<pre class=\"example\" id=\"org0f1468f\">{{{my-button(&quot;Using Macro&quot;, #?(:cljs (fn [] (js/alert &quot;Hello From Macro!&quot;))))}}}\n</pre>\n\n</pre>\n\n<pre class=\"orgx\" data-wrapper=\"use-defui\" data-wrapper-data=\"macro-result\"><p>\n<code class=\"orgx\">\n($ my-button {:callback (or  #?(:cljs (fn [] (js/alert &quot;Hello From Macro!&quot;))) nil)} &quot;Using Macro&quot;)\n</code>\n</p>\n\n</pre>\n\n<pre class=\"orgx\">($ showcase {:showcase-name &quot;Rendering&quot; :class &quot;lg:grid-cols-[minmax(0,1fr)_minmax(0,0.5fr)]&quot;}\n  ($ tabs {:tab-list [{:name &quot;Inline OrgX with Macro&quot; :content ($ macro-example)}]})\n  ($ macro-result))\n\n</pre>\n</div>\n</div>\n</div>\n<div id=\"outline-container-builtin-components\" class=\"outline-2\">\n<a href=\"#builtin-components\"><h2 id=\"builtin-components\" class=\"cr-self-reference \">Builtin Components</h2></a>\n<div class=\"outline-text-2\" id=\"text-builtin-components\">\n<p>\nThe blogging program provides several builtin components, I will briefly describe their features.\n</p>\n</div>\n<div id=\"outline-container-simple-remarks\" class=\"outline-3\">\n<a href=\"#simple-remarks\"><h3 id=\"simple-remarks\" class=\"cr-self-reference \">Simple Notice Blocks</h3></a>\n<div class=\"outline-text-3\" id=\"text-simple-remarks\">\n<p>\nIt provides most commons blocks like <code>info</code>, <code>note</code>, <code>warn</code> and <code>error</code>.\n</p>\n\n<pre class=\"orgx\" data-wrapper=\"use-defui\" data-wrapper-data=\"remarks_example\"><pre class=\"example\" id=\"orgf924c87\">#+begin_orgx_info\nThis is an info\n#+end_orgx_info\n\n#+begin_orgx_note\nThis is a note\n#+end_orgx_note\n\n#+begin_orgx_warn\nThis is a warn\n#+end_orgx_warn\n\n#+begin_orgx_error\nThis is an error\n#+end_orgx_error\n\n</pre>\n\n</pre>\n\n<pre class=\"orgx\" data-wrapper=\"use-defui\" data-wrapper-data=\"remarks_result\"><pre class=\"orgx\" data-wrapper=\"use-comp\" data-wrapper-data=\"info\"><p>\nThis is an info\n</p>\n\n</pre>\n<pre class=\"orgx\" data-wrapper=\"use-comp\" data-wrapper-data=\"note\"><p>\nThis is a note\n</p>\n\n</pre>\n<pre class=\"orgx\" data-wrapper=\"use-comp\" data-wrapper-data=\"warn\"><p>\nThis is a warn\n</p>\n\n</pre>\n<pre class=\"orgx\" data-wrapper=\"use-comp\" data-wrapper-data=\"error\"><p>\nThis is an error\n</p>\n\n</pre>\n\n</pre>\n\n<pre class=\"orgx\">($ showcase {:showcase-name &quot;Rendering&quot;}\n  ($ tabs {:tab-list [{:name &quot;Remarks&quot; :content ($ remarks_example)}]})\n  ($ remarks_result))\n\n</pre>\n</div>\n</div>\n<div id=\"outline-container-tabs\" class=\"outline-3\">\n<a href=\"#tabs\"><h3 id=\"tabs\" class=\"cr-self-reference \">Tabs</h3></a>\n<div class=\"outline-text-3\" id=\"text-tabs\">\n<pre class=\"orgx\" data-wrapper=\"use-defui\" data-wrapper-data=\"code_tabs\"><div class=\"org-src-container\">\n<pre class=\"cr-highlighted\"><code class=\"lang-clojure\"><html><head></head><body>(<span class=\"hljs-name\">defui</span> tabs [{<span class=\"hljs-symbol\">:keys</span> [tab-list default-table class]}]\n  (<span class=\"hljs-name\"><span class=\"hljs-built_in\">let</span></span> [[selected-tab set-selected-tab!] (<span class=\"hljs-name\">use-state</span> (<span class=\"hljs-name\"><span class=\"hljs-built_in\">or</span></span> default-table\n                                                        (<span class=\"hljs-symbol\">:name</span> (<span class=\"hljs-name\"><span class=\"hljs-built_in\">first</span></span> tab-list))))]\n    ($ <span class=\"hljs-symbol\">:div.my-4.relative.border-sky-300.border-l-2.border-l-neutral-100</span> {<span class=\"hljs-symbol\">:class</span> class}\n       ($ <span class=\"hljs-symbol\">:div.my-0.flex.relative.bg-neutral-100</span>\n          (<span class=\"hljs-name\"><span class=\"hljs-built_in\">map</span></span> (<span class=\"hljs-name\"><span class=\"hljs-built_in\">fn</span></span> [{<span class=\"hljs-symbol\">:keys</span> [name]}]\n                 ($ <span class=\"hljs-symbol\">:button.font-medium.text-neutral-700.bg-neutral-50.py-1.px-2.border-t-2.border-neutral-50.min-w-28.bg-neutral-50.border-t-neutral-100</span>\n                    {<span class=\"hljs-symbol\">:key</span> name\n                     <span class=\"hljs-symbol\">:class</span> (<span class=\"hljs-name\"><span class=\"hljs-built_in\">when</span></span> (<span class=\"hljs-name\"><span class=\"hljs-built_in\">=</span></span> name selected-tab)\n                              <span class=\"hljs-string\">&quot; text-sky-800 border-sky-400 bg-sky-100 border-t-sky-400&quot;</span>)\n                     <span class=\"hljs-symbol\">:on-click</span> (<span class=\"hljs-name\"><span class=\"hljs-built_in\">fn</span></span> []\n                                 #?(<span class=\"hljs-symbol\">:cljs</span>\n                                    (<span class=\"hljs-name\">set-selected-tab!</span> name)))}\n                    name))\n               tab-list))\n       ($ <span class=\"hljs-symbol\">:div.my-0.bg-neutral-50.overflow-hidden.px-2.h-full</span>\n          (<span class=\"hljs-symbol\">:content</span> (<span class=\"hljs-name\"><span class=\"hljs-built_in\">first</span></span> (<span class=\"hljs-name\"><span class=\"hljs-built_in\">filter</span></span> (<span class=\"hljs-name\"><span class=\"hljs-built_in\">fn</span></span> [{<span class=\"hljs-symbol\">:keys</span> [name]}]\n                                     (<span class=\"hljs-name\"><span class=\"hljs-built_in\">=</span></span> name selected-tab))\n                                   tab-list)))))))\n</body></html></code></pre>\n</div>\n\n</pre>\n\n<pre class=\"orgx\" data-wrapper=\"use-defui\" data-wrapper-data=\"tabs_example\"><pre class=\"example\" id=\"orgba7f7a5\">#+begin_orgx\n($ tabs {:tab-list [{:name &quot;tabs.clj&quot; :content ($ code_tabs)}\n                    {:name &quot;tabs usage&quot; :content ($ tabs_example)}]})\n#+end_orgx\n</pre>\n\n</pre>\n\n\n<pre class=\"orgx\" data-wrapper=\"use-defui\" data-wrapper-data=\"tabs_result\"><pre class=\"orgx\">($ tabs {:tab-list [{:name &quot;tabs.clj&quot; :content ($ code_tabs)}\n                      {:name &quot;tabs usage&quot; :content ($ tabs_example)}]})\n\n</pre>\n\n</pre>\n\n<p>\n<code>tabs</code> is like tabs in a browser or a text editor.\n</p>\n<pre class=\"orgx\">($ showcase {:showcase-name &quot;Rendering&quot;}\n  ($ tabs {:tab-list [{:name &quot;tabs usage&quot; :content ($ tabs_example)}]})\n  ($ tabs_result))\n\n</pre>\n</div>\n</div>\n<div id=\"outline-container-split-layout\" class=\"outline-3\">\n<a href=\"#split-layout\"><h3 id=\"split-layout\" class=\"cr-self-reference \">Split Layout</h3></a>\n<div class=\"outline-text-3\" id=\"text-split-layout\">\n<p>\nSplit layout lets you show two things side by side:\n</p>\n\n<pre class=\"example\" id=\"org2aaa82a\">#+attr_orgx_defui: true\n#+begin_orgx_split_1\n#+begin_src clojure\n  ($ :button {:class &quot;bg-sky-600 text-neutral-50 py-1 px-2 rounded-lg&quot;\n              :on-click (fn [&amp; _]\n                          #?(:cljs (js/alert &quot;clicked!&quot;)))}\n     &quot;Click Me&quot;)\n#+end_src\n#+end_orgx_split_1\n\n#+attr_orgx_defui: true\n#+begin_orgx_split_2\n#+begin_orgx\n  ($ :button {:class &quot;bg-sky-600 text-neutral-50 py-1 px-2 rounded-lg&quot;\n              :on-click (fn [&amp; _]\n                          #?(:cljs (js/alert &quot;clicked!&quot;)))}\n     &quot;Click Me&quot;)\n#+end_orgx\n#+end_orgx_split_2\n\n#+begin_orgx\n($ split-layout\n($ tabs {:tab-list [{:name &quot;button&quot; :content ($ split_1)}]})\n($ tabs {:tab-list [{:name &quot;showcase&quot; :content ($ split_2)}]}))\n#+end_orgx\n</pre>\n\n<p>\nWill be rendered as:\n</p>\n\n\n<pre class=\"orgx\" data-wrapper=\"use-defui\" data-wrapper-data=\"split_1\"><div class=\"org-src-container\">\n<pre class=\"cr-highlighted\"><code class=\"lang-clojure\"><html><head></head><body>($ <span class=\"hljs-symbol\">:button</span> {<span class=\"hljs-symbol\">:class</span> <span class=\"hljs-string\">&quot;bg-sky-600 text-neutral-50 py-1 px-2 rounded-lg&quot;</span>\n            <span class=\"hljs-symbol\">:on-click</span> (<span class=\"hljs-name\"><span class=\"hljs-built_in\">fn</span></span> [&amp; _]\n                        #?(<span class=\"hljs-symbol\">:cljs</span> (<span class=\"hljs-name\">js/alert</span> <span class=\"hljs-string\">&quot;clicked!&quot;</span>)))}\n   <span class=\"hljs-string\">&quot;Click Me&quot;</span>)\n</body></html></code></pre>\n</div>\n\n</pre>\n\n<pre class=\"orgx\" data-wrapper=\"use-defui\" data-wrapper-data=\"split_2\"><pre class=\"orgx\">  ($ :button {:class &quot;bg-sky-600 text-neutral-50 py-1 px-2 rounded-lg&quot;\n              :on-click (fn [&amp; _]\n                          #?(:cljs (js/alert &quot;clicked!&quot;)))}\n     &quot;Click Me&quot;)\n\n</pre>\n\n</pre>\n\n<pre class=\"orgx\">($ split-layout\n($ tabs {:tab-list [{:name &quot;button&quot; :content ($ split_1)}]})\n($ tabs {:tab-list [{:name &quot;showcase&quot; :content ($ split_2)}]}))\n\n</pre>\n</div>\n</div>\n<div id=\"outline-container-showcase\" class=\"outline-3\">\n<a href=\"#showcase\"><h3 id=\"showcase\" class=\"cr-self-reference \">Showcase</h3></a>\n<div class=\"outline-text-3\" id=\"text-showcase\">\n<p>\nShowcase is a simple wrapper over <code>split-layout</code> and <code>tabs</code>. The <code>showcase</code> component is used extensive in this post, such as the example in <a href=\"#simple-remarks\">Simple Notice Blocks</a> is coded as:\n</p>\n\n<pre class=\"example\" id=\"orga398f69\">#+attr_orgx_defui: true\n#+begin_orgx_remarks_example\n#+begin_example\n#+begin_orgx_info\nThis is an info\n#+end_orgx_info\n\n#+begin_orgx_note\nThis is a note\n#+end_orgx_note\n\n#+begin_orgx_warn\nThis is a warn\n#+end_orgx_warn\n\n#+begin_orgx_error\nThis is an error\n#+end_orgx_error\n\n#+end_example\n#+end_orgx_remarks_example\n\n#+attr_orgx_defui: true\n#+begin_orgx_remarks_result\n#+begin_orgx_info\nThis is an info\n#+end_orgx_info\n#+begin_orgx_note\nThis is a note\n#+end_orgx_note\n#+begin_orgx_warn\nThis is a warn\n#+end_orgx_warn\n#+begin_orgx_error\nThis is an error\n#+end_orgx_error\n#+end_orgx_remarks_result\n\n#+begin_orgx\n($ showcase {:showcase-name &quot;Rendering&quot;}\n  ($ tabs {:tab-list [{:name &quot;Remarks&quot; :content ($ remarks_example)}]})\n  ($ remarks_result))\n#+end_orgx\n</pre>\n</div>\n</div>\n</div>\n<div id=\"outline-container-conclusions\" class=\"outline-2\">\n<a href=\"#conclusions\"><h2 id=\"conclusions\" class=\"cr-self-reference \">Conclusions</h2></a>\n<div class=\"outline-text-2\" id=\"text-conclusions\">\n</div>\n<div id=\"outline-container-caveats\" class=\"outline-3\">\n<a href=\"#caveats\"><h3 id=\"caveats\" class=\"cr-self-reference \">Caveats</h3></a>\n<div class=\"outline-text-3\" id=\"text-caveats\">\n<p>\nAlthough I have extensively used it in this demostration and will definitely use it in the future, there are some notably deficiency with the current implementation.\n</p>\n\n<ul class=\"org-ul\">\n<li>You need to read the logging to understand the problem if anything goes wrong. If you want to do SSR or SSG, the fact that the same code must be run on the JVM and the browser and produce the same result adds complexity.</li>\n<li>The syntax still feels cumbersome in many cases, but that might be improved in the future.</li>\n<li>The current implementation requires Emacs itself to convert the Org files into HTML, and Clojure code will then process the HTML. The most notably advantage of this method is that we can use the (basically) the full power of Org mode. However, it is also a lot of moving parts.</li>\n</ul>\n</div>\n</div>\n<div id=\"outline-container-future-plans\" class=\"outline-3\">\n<a href=\"#future-plans\"><h3 id=\"future-plans\" class=\"cr-self-reference \">Future Plans</h3></a>\n<div class=\"outline-text-3\" id=\"text-future-plans\">\n<p>\nI will describe the process of implement it in the next post of this series. Current the code is still coupled with my blogging program. I'm planning on make it a separate library in the future.\n</p>\n</div>\n</div>\n</div>\n",
       :orgx-require [[clojure.pprint :as pprint]],
       :modified-date "2026-01-03T15:10:59+08:00"}

Use Other OrgX Files as Components

By default, OrgX files are compiled as Cljc files and will be put in the orgx namespace. You can import them as described in Import Modules.

Use OrgX With Native Org Syntax

Use Components

Writing #+begin_orgx and Clojure code must be very tedious every time we want to use a simple component, like note or warning notice blocks.

To solve this problem, a new syntax #+orgx_{comp-name} has been introduced.

For example:

Use Component With Org Syntax:

#+begin_orgx_note
This is a note

+ /Normal/ Org markups *can* be used inside it

@@orgx:($ :span "You can even nest OrgX syntax in it")@@
#+end_orgx_note

Rendering:

This is a note

Normal Org markups can be used inside it

You can even nest OrgX syntax in it

It works by passing the rendered content to the component note as children. All other Org markups or structures that can be used in an Org environment can also be used here. You can also nested other OrgX structures in it, except for top level Clojure definition and component building, which are not supported.

Currently we can't pass other properties to the component using this syntax, but that might change in the future.

Build Components

Something we may want to build a React component out of some Org blocks. Like we may want to pass two Org mode source blocks as arguments to a tabs components. To do this, we just need to add an annotation to the existing #+begin_orgx_{comp-name} syntax:

#+attr_orgx_defui: true
#+begin_orgx_my-note
*@@orgx:(or (:note-text props) "Tip")@@*
#+begin_orgx
(:children props)
#+end_orgx
#+end_orgx_my-note

As shown in the example, we can use normal Org syntax along with OrgX snippets. We can also access the properties with the props variable.

In the above example we have defined a my-note component, we can then use it with any aforementioned methods.

Example Usage:

#+begin_orgx_my-note
This is a note!
#+end_orgx_my-note

Rendering:

Tip

This is a note!

Inline OrgX with Macros

Currently no similar syntax for inline OrgX is supported, however, it is fairly easy to make life easier with macros. Let's go back to use my-button as the example.

Inline OrgX with Macro:

We can define a macro like:

#+MACRO: my-button @@orgx:($ my-button {:callback (or $2 nil)} $1)@@

And then use it with:

{{{my-button("Using Macro", #?(:cljs (fn [] (js/alert "Hello From Macro!"))))}}}

Rendering:

Builtin Components

The blogging program provides several builtin components, I will briefly describe their features.

Simple Notice Blocks

It provides most commons blocks like info, note, warn and error.

Remarks:

#+begin_orgx_info
This is an info
#+end_orgx_info

#+begin_orgx_note
This is a note
#+end_orgx_note

#+begin_orgx_warn
This is a warn
#+end_orgx_warn

#+begin_orgx_error
This is an error
#+end_orgx_error

Rendering:

This is an info

This is a note

This is a warn

This is an error

Tabs

tabs is like tabs in a browser or a text editor.

tabs usage:

#+begin_orgx
($ tabs {:tab-list [{:name "tabs.clj" :content ($ code_tabs)}
                    {:name "tabs usage" :content ($ tabs_example)}]})
#+end_orgx

Rendering:

tabs.clj:

(defui tabs [{:keys [tab-list default-table class]}]
  (let [[selected-tab set-selected-tab!] (use-state (or default-table
                                                        (:name (first tab-list))))]
    ($ :div.my-4.relative.border-sky-300.border-l-2.border-l-neutral-100 {:class class}
       ($ :div.my-0.flex.relative.bg-neutral-100
          (map (fn [{:keys [name]}]
                 ($ :button.font-medium.text-neutral-700.bg-neutral-50.py-1.px-2.border-t-2.border-neutral-50.min-w-28.bg-neutral-50.border-t-neutral-100
                    {:key name
                     :class (when (= name selected-tab)
                              " text-sky-800 border-sky-400 bg-sky-100 border-t-sky-400")
                     :on-click (fn []
                                 #?(:cljs
                                    (set-selected-tab! name)))}
                    name))
               tab-list))
       ($ :div.my-0.bg-neutral-50.overflow-hidden.px-2.h-full
          (:content (first (filter (fn [{:keys [name]}]
                                     (= name selected-tab))
                                   tab-list)))))))

tabs usage:

#+begin_orgx
($ tabs {:tab-list [{:name "tabs.clj" :content ($ code_tabs)}
                    {:name "tabs usage" :content ($ tabs_example)}]})
#+end_orgx

Split Layout

Split layout lets you show two things side by side:

#+attr_orgx_defui: true
#+begin_orgx_split_1
#+begin_src clojure
  ($ :button {:class "bg-sky-600 text-neutral-50 py-1 px-2 rounded-lg"
              :on-click (fn [& _]
                          #?(:cljs (js/alert "clicked!")))}
     "Click Me")
#+end_src
#+end_orgx_split_1

#+attr_orgx_defui: true
#+begin_orgx_split_2
#+begin_orgx
  ($ :button {:class "bg-sky-600 text-neutral-50 py-1 px-2 rounded-lg"
              :on-click (fn [& _]
                          #?(:cljs (js/alert "clicked!")))}
     "Click Me")
#+end_orgx
#+end_orgx_split_2

#+begin_orgx
($ split-layout
($ tabs {:tab-list [{:name "button" :content ($ split_1)}]})
($ tabs {:tab-list [{:name "showcase" :content ($ split_2)}]}))
#+end_orgx

Will be rendered as:

button:

($ :button {:class "bg-sky-600 text-neutral-50 py-1 px-2 rounded-lg"
            :on-click (fn [& _]
                        #?(:cljs (js/alert "clicked!")))}
   "Click Me")

showcase:

Showcase

Showcase is a simple wrapper over split-layout and tabs. The showcase component is used extensive in this post, such as the example in Simple Notice Blocks is coded as:

#+attr_orgx_defui: true
#+begin_orgx_remarks_example
#+begin_example
#+begin_orgx_info
This is an info
#+end_orgx_info

#+begin_orgx_note
This is a note
#+end_orgx_note

#+begin_orgx_warn
This is a warn
#+end_orgx_warn

#+begin_orgx_error
This is an error
#+end_orgx_error

#+end_example
#+end_orgx_remarks_example

#+attr_orgx_defui: true
#+begin_orgx_remarks_result
#+begin_orgx_info
This is an info
#+end_orgx_info
#+begin_orgx_note
This is a note
#+end_orgx_note
#+begin_orgx_warn
This is a warn
#+end_orgx_warn
#+begin_orgx_error
This is an error
#+end_orgx_error
#+end_orgx_remarks_result

#+begin_orgx
($ showcase {:showcase-name "Rendering"}
  ($ tabs {:tab-list [{:name "Remarks" :content ($ remarks_example)}]})
  ($ remarks_result))
#+end_orgx

Conclusions

Caveats

Although I have extensively used it in this demostration and will definitely use it in the future, there are some notably deficiency with the current implementation.

You need to read the logging to understand the problem if anything goes wrong. If you want to do SSR or SSG, the fact that the same code must be run on the JVM and the browser and produce the same result adds complexity.
The syntax still feels cumbersome in many cases, but that might be improved in the future.
The current implementation requires Emacs itself to convert the Org files into HTML, and Clojure code will then process the HTML. The most notably advantage of this method is that we can use the (basically) the full power of Org mode. However, it is also a lot of moving parts.

Future Plans

I will describe the process of implement it in the next post of this series. Current the code is still coupled with my blogging program. I'm planning on make it a separate library in the future.

Watching Files with java.nio.file.WatchService and Clojure

2025-12-13T22:18:29+08:00

Recently I want to have a utility in Clojure that can notify me when there is a change happened in some specified directory. Fortunately Java seems to natively support it by providing a java.nio.file.WatchService. It seems trivial so I want to use it directly in Clojure instead of adding another dependency to my project. It turns out to be sightly more complicated than I expected. Let me explain.

The Problem

The challenge mainly lies in the fact that, Java doesn't natively support recursively watching a directory. If we want this behavoir, we have to implement it ourselves.

(def ^:dynamic *chan-size* 512)

(defn register [^Path path ^WatchService watch-service]
  (.register path
             watch-service
             (into-array WatchEvent$Kind
                         [StandardWatchEventKinds/ENTRY_CREATE
                          StandardWatchEventKinds/ENTRY_DELETE
                          StandardWatchEventKinds/ENTRY_MODIFY
                          StandardWatchEventKinds/OVERFLOW])))

(defn watch [& paths]
  (let [resp-chan (a/chan *chan-size*)
        cancel-chan (a/chan 1)
        stopped? (atom false)

        worker
        (future
          (let [paths (map (fn [p]
                             (Path/of p (into-array String [])))
                           paths)
                watch-service (-> (java.nio.file.FileSystems/getDefault)
                                  (.newWatchService))]
            (doseq [path paths]
              (doseq [^File subpath-file (file-seq (.toFile path))]
                (when (.isDirectory subpath-file)
                  (register (.toPath subpath-file)
                            watch-service))))
            (try
              (while (not @stopped?)
                (let [watch-key (.take watch-service)
                      events (.pollEvents watch-key)
                      ^Path parent-dir (.watchable watch-key)]
                  (doseq [^WatchEvent event events]
                    (let [^WatchEvent$Kind kind (.kind event)
                          ^Path event-path (.context event)
                          ^Path resolved-path (.resolve parent-dir event-path)]
                      (a/>!! resp-chan
                             {:kind (case (.name kind)
                                      "ENTRY_CREATE" :entry-create
                                      "ENTRY_MODIFY" :entry-modify
                                      "ENTRY_DELETE" :entry-delete
                                      "OVERFLOW" :overflow)
                              :path resolved-path})

                      ;; If the newly created object is a directory,
                      ;;   we recursively register files in it.
                          (when (and (= kind StandardWatchEventKinds/ENTRY_CREATE)
                                 (.isDirectory (.toFile resolved-path)))
                        (doseq [^File subpath-file (file-seq (.toFile resolved-path))]
                          (when (.isDirectory subpath-file)
                            (register (.toPath subpath-file)
                                      watch-service))))
                      (.reset watch-key)))))
              (catch InterruptedException _)
              (finally
                (.close watch-service)))))

        sentinel (future
                   (while (not (a/<!! cancel-chan)))
                   (reset! stopped? true)
                   (future-cancel worker)
                   (a/close! resp-chan)
                   (a/close! cancel-chan))]
    (with-meta [resp-chan cancel-chan]
      {:debug {:worker worker
               :sentinel sentinel
               :stopped? stopped?}})))

The initial implementation looks like this, which is fairly straightforward. We start by recursively registering files in the directories provided by paths argument, and if there is a newly created directory, we also recursively register its contents. Clojure provides a file-seq function that makes this task much easier. For an example usage of this code, check the end of this post.

However, there is only one issue: If a file is created in a subdirectory before the subdirectory got registered, the event won't be fired.

+---------------+
| worker thread |
+-------+-------+
        +                 +---------------+
        +-----------------| create subdir |
        |                 +---------------+
+-------+---------------+
| event: subdir created |
+-------+---------------+    
        |                 +------------------------+
        +-----------------+ new file in the subdir |
        |                 +------------------------+
+-------+-----------+
| subdir registered |
+-------------------+

The Workaround

We can have a workaround of this by emitting an event of each file in the newly created directory, like this:

(when (and (= kind StandardWatchEventKinds/ENTRY_CREATE)
           (.isDirectory (.toFile resolved-path)))

  (register resolved-path
            watch-service)

  (doseq [^File subpath-file (rest (file-seq (.toFile resolved-path)))]
    (when (.isDirectory subpath-file)
      (register (.toPath subpath-file)
                watch-service))
    (a/>!! resp-chan
           {:kind :entry-create
            :path (.toPath subpath-file)})))

However, it introduces a new problem. If a file is created in a subdirectory after be subdirectory is regsitered, but before the subdirectories scanning is finished. The event of the file may be emitted twice.

  +---------------+
  | worker thread |
  +-------+-------+
          +                +----------------+
          +----------------+ subdir created |
          |                +----------------+
          |
 +--------+----------+
 | subdir registered |
 +--------+----------+
          |              +-------------------------+
          |--------------+ file1 created in subdir |
          |              +-------------------------+
 +--------+---------+
 | scan: find file1 |
 +--------+---------+  
          |               
          |               
+---------+------------+ 
| event: file1 created |
+----------------------+

We have three choices here, we can:

ignore this issue, treat it as something acceptable.
discard the workaround all together, let the user scan if there is any new file in the newly created directory.
memorize all the files detected, check if the event has already been fired if a new file is detected.

In my case, the first option is good enough, however, it got me curious about how this issue is handled by other projects.

How is it Handled by Other Projects?

chokidar

chokidar is a famous file watching library in JavaScript. It seems to have chosen the third option:

// handler.ts
// line starting from 575

// Files that present in current directory snapshot
// but absent in previous are added to watch list and
// emit `add` event.
if (item === target || (!target && !previous.has(item))) {
  this.fsw._incrReadyCount();

  // ensure relativeness of path is preserved in case of watcher reuse
  path = sp.join(dir, sp.relative(dir, path));

  this._addToNodeFs(path, initialAdd, wh, depth + 1);
}

inotify-tools

inotify-tools is a set of cli tools providing interface to inotify. It was written in C++ and newer version is rewritten in Rust.

By default, inotify-wait quits after it detected a change. Therefore the problem described in the previous section is naturally up to the user to solve.

It also provides an --monitor option to continuously monitoring the changes happened in a directory. With --monitor on, it seems to choose the second option described in the previous section.

> inotifywait -mr -e create .

Setting up watches.  Beware: since -r was given, this may take a while!
Watches established.

# executing `mkdir -p s1/s2/s3/s4` in another shell session

./ CREATE,ISDIR s1
Watching new directory ./s1/

If we create the directories one by one, all the directories will be notified. However, by using -p option to create multiple level of directories at once. Only the first one will be notified.

We can further confirm it by reading the source code:

// inotifywait.cpp
// L391, main function

do {
  event = inotifytools_next_event(timeout);

  /*
   * ......
   */

  if (monitor && recursive) {
    if ((event->mask & IN_CREATE) ||
        (!moved_from && (event->mask & IN_MOVED_TO))) {
      // New file - if it is a directory, watch it
      char *new_file = inotifytools_dirpath_from_event(event);
      if (new_file && *new_file && isdir(new_file)) {
        if (!quiet) {
          output_error(sysl, "Watching new directory %s\n", new_file);
        }
        if (!inotifytools_watch_recursively(new_file, events)) {
          output_error(sysl, "Couldn't watch new directory %s: %s\n", new_file,
                       strerror(inotifytools_error()));
        }
      }
      free(new_file);
    } 

    /*
     * ......
     */
  }
  fflush(NULL);
} while (monitor)

The program constantly polls and prints new events in the main function. If the newly created object is a directory and --recursive option is on, it recursively watch the newly created directory. However, it won't print files in the new directory if we check the inotifytools_watch_recursively function.

Conclusion

There doesn't seem to a definitive solution to this issue. The workaround described in section 2 seems to be good enough in my case. I will conclude this post by posing a simple example usage of the code with the workaround applied.

(deftest wach_service_example
  (testing ""
    (let [test-dir (str *test-dir* "/example")]
      (.mkdirs (io/file test-dir))
      (let [[resp cancel] (subject/watch test-dir)
            worker (future
                     (loop [event (a/<!! resp)
                            result (transient [])]
                       (if (not (nil? event))
                         (recur (a/<!! resp)
                                (conj! result
                                       {:kind (:kind event)
                                        :path (.toString (:path event))}))
                         (persistent! result))))]
        (.sleep java.util.concurrent.TimeUnit/MILLISECONDS 200)
        (.mkdirs (io/file (str test-dir "/s1/s2")))
        (.createNewFile (io/file (str test-dir "/s1/s2/file")))
        ;; We can't delete the files too quickly after they are created,
        ;;    otherwise we will receive no event.
        (.sleep java.util.concurrent.TimeUnit/MILLISECONDS 200)
        (doseq [f (reverse (rest (file-seq (io/file test-dir))))]
          (.delete f))
        (.sleep java.util.concurrent.TimeUnit/MILLISECONDS 200)
        ;; shutdown the watch service
        (a/>!! cancel true)

        ;; verify the result
        (is (= [{:kind :entry-create,		  
                         :path "test/resource/watch_service_test/example/s1"}
                        {:kind :entry-create,
                         :path "test/resource/watch_service_test/example/s1/s2"}
                        {:kind :entry-create,
                         :path "test/resource/watch_service_test/example/s1/s2/file"}
                        {:kind :entry-delete,
                         :path "test/resource/watch_service_test/example/s1/s2/file"}
                        {:kind :entry-delete,
                         :path "test/resource/watch_service_test/example/s1/s2"}
                        {:kind :entry-delete,
                         :path "test/resource/watch_service_test/example/s1"}]
               @worker))))))

You can also find the source code and some unit tests here.

My Experience with lsp-bridge

2025-11-22T23:33:09+08:00

The experience of using lsp-mode or elgot depends heavily on the lsp server you are using and the project you are working on. With the newly added JSON parser in Emacs 30 and the garbage collecting improvements in the igc branch, the experience of lsp-mode or eglot can be more than good enough. Still, if you are using the more demanding lsp server (like some language servers for frontend development) or working on a larger-size project, the experience could still be unsatisfying or even super frustrating. If you have ever experienced Emacs freezing after checkout to another git branch or big gc lag when using gcmh-mode, you could still consider giving lsp-bridge a try.

In exchange for speed and fluency, lsp-bridge replaces every builtin and well known tools that aren't suitable for async operations, including but not limited to completion-at-point, xref, eldoc. This prevents a lot of users from ever trying it, and that's reasonable. However, the async nature of lsp-bridge also brings its own advantages.

For a small example, consider that even the go-to-definition operation in lsp-bridge is asynchronous. With other lsp clients, Emacs is stuck between the time you call xref-find-definitions and the lsp server returns a response. With lsp-bridge, even if you are waiting for a response, Emacs is free to do other things in the meantime, such as doing a garbage collection, or executing a callback registered by run-with-idle-timer.

Finally, you certainly can use lsp-bridge only for some modes and keep using completion-at-point for other modes. That's also what I'm doing.

Basic Setup

To use lsp-bridge, you first need to install some external dependencies.

pip3 install epc orjson sexpdata six setuptools paramiko rapidfuzz watchdog packaging

If you are using Nix, you need to add a python package with dependencies to your Nix config files.

(python3.withPackages (
      ps: with ps; [
        # ...
        epc
        orjson
        packaging
        paramiko
        rapidfuzz
        setuptools
        sexpdata
        six
        watchdog
      ]
    ))

With external dependencies installed, now we can install the lsp-bridge package. Here's how I have done it with straight and use-package.

(use-package lsp-bridge
  :hook
  (clojure-mode . lsp-bridge-mode)
  (clojure-ts-mode . lsp-bridge-mode)
  (typescript-ts-mode . lsp-bridge-mode)
  (js-ts-mode . lsp-bridge-mode)
  (java-ts-mode . lsp-bridge-mode)
  :straight '(lsp-bridge :type git :host github :repo "manateelazycat/lsp-bridge"
                         :files (:defaults "*.el" "*.py" "acm" "core" "langserver" "multiserver" "resources")
                         :build (:not compile))

  :init
  (defun me/lsp-bridge-corfu-hook ()
    (when (and lsp-bridge-mode
               (boundp 'corfu-mode)
               corfu-mode)
      (corfu-mode -1)))
  (add-hook 'corfu-mode-hook #'me/lsp-bridge-corfu-hook))

Here I only enabled lsp-bridge-mode for modes in the :hook part, and I disabled corfu in lsp-bridge-mode-hook (I'm still using it for other programming or writing tasks).

Unlike lsp-mode, lsp-bridge doesn't provide a lsp server installation function. Check Supported language servers and their corresponding pages for installation methods.

If the server is installed and lsp-bridge-mode is enabled, it should just work without any other configurations. If it doesn't, set lsp-bridge-enable-debug to true and check *lsp-bridge* for error messages.

Configuration

Keymapping

lsp-bridge provides its xef and eldoc equivalents, but it's up to us to mapping them. Here is what I do just for a reference.

(general-evil-define-key '(normal) '(lsp-bridge-mode-map)
  "s S" #'lsp-bridge-workspace-list-symbols
  "s D" #'lsp-bridge-diagnostic-list
  "s R" #'lsp-bridge-rename
  "g d" #'lsp-bridge-find-def
  "g r" #'lsp-bridge-find-references
  "g D" #'lsp-bridge-find-impl
  "C-RET" #'lsp-bridge-code-action
  "C-<return>" #'lsp-bridge-code-action)

In corfu you can set minimum popup width with corfu-min-width. lsp-bridge~/~acm currently doesn't provide a way to do so. However it is relatively easy to hack one.

(setq me/acm-minimum-width 1000)

(defun me/acm-minimum-width-function (oldfun &rest r)
  (let ((result (apply oldfun r)))
    (max me/acm-minimum-width result)))

(advice-add 'acm-menu-max-length :around #'me/acm-minimum-width-function)

flymake

There is actually a third-party lsp-bridge integration for flymake. Check eki3z/flymake-bridge.

Workspace Management

lsp-bridge's workspace detection depends entirely on git. It simply use the nearest directory contains .git as the workspace root. This may not be enough for some use cases. However, it provides a lsp-bridge-get-project-path-by-filepath for us to customize. We can implement something similar to what lsp-mode provides fairly easily.

(require 'f)

;; assume savehist-mode is enabled
(defvar me/lsp-bridge-workspaces (list))
(add-to-list 'savehist-additional-variables 'me/lsp-bridge-workspaces)

(defun me/lsp-bridge-workspace-add (project-root)
  (interactive
   (list (read-directory-name "Select folder:")))
  (add-to-list 'me/lsp-bridge-workspaces project-root))

(defun me/lsp-bridge-workspace-remove (project-root)
  (interactive (list (completing-read "Select folder to remove: "
                                      me/lsp-bridge-workspaces)))
  (setq me/lsp-bridge-workspaces (cl-remove project-root me/lsp-bridge-workspaces :test #'equal)))

(defun me/lsp-bridge-get-workspace (path)
  (cl-first (cl-mapcar #'f-expand
                       (cl-remove-if-not (lambda (workspace)
                                           (if (f-ancestor-of? (f-expand workspace) path)
                                                   workspace                                  
                                             nil))
                                         me/lsp-bridge-workspaces))))

(setq lsp-bridge-get-project-path-by-filepath #'me/lsp-bridge-get-workspace)

Working with Java

We need a few more lines of configuration to make it works with Java.

(use-package lsp-bridge
  ;; ...
  :init
  (require 'lsp-bridge-jdtls)
  (setq lsp-bridge-enable-auto-import t)
  ;; ... other configurations
  )

Working with Clojure and Cider

When writing Clojure, I would like to use cider for completion and let lsp handling everything else. With lsp-mode we can just locally set lsp-enable-completion-at-point to false. With lsp-bridge, well, we can disable lsp-bridge's automatic popup and continue to use corfu.

(use-package lsp-bridge
  ;; ...
  ;; add a new variable
  (defvar me/force-corfu nil)

  ;; change the previous hook to this
  (defun me/lsp-bridge-corfu-hook ()
    (when (and lsp-bridge-mode
               (boundp 'corfu-mode)
               corfu-mode
               (not me/force-corfu))
      (corfu-mode -1))))

(use-package cider
  :after lsp-bridge
  :config
  (defun me/lsp-bridge-cider-hook ()
    (when cider-mode
      (setq-local me/force-corfu t)
      (setq-local lsp-bridge-complete-manually t)
      (corfu-mode 1)))
  (add-hook 'cider-mode-hook #'me/lsp-bridge-cider-hook 80))

Conclusion

Overall I would say I'm satisfied with what lsp-bridge provides and amazed at its fluency. I can now load and browse through graaljs's source code with no stutter, no random freeze I need to C-g, that may or may not work, no nothing. The strategy of off-loading computation to an external process and async everything seems to put very light weight on the Emacs side and work really well.

Experiment with GraalVM, Clojure, and JavaScript

2025-11-18T15:03:31+08:00

A common challenge when making a fullstack website using Clojure/ClojureScript is that, we are often required to use a JavaScript library on the server side when doing Server Side Rendering (SSR). GraalVM/GraalJS provides a solution to run JavaScript code on the JVM. If only we could harness that power…

This blog describes the basic usage of GraalJS and what I managed to achieve with GraalJS and Clojure.

Basic Setup and a Hello World Program

We add the following dependencies to our deps.edn

:deps {org.clojure/clojure {:mvn/version "1.11.1"}
       org.graalvm.polyglot/polyglot {:mvn/version "25.0.1"}
       org.graalvm.js/js-language {:mvn/version "25.0.1"}
       org.graalvm.truffle/truffle-runtime {:mvn/version "25.0.1"}}

With the dependencies installed, we can write a Hello World program.

(ns your-namespace
  (:import
   [org.graalvm.polyglot Context]))


(defonce ^:dynamic *context*
  (-> (Context/newBuilder (into-array String ["js"]))
      (.build)))

(def hello-fn (.eval *context*
                     "js"
                     "(function (name) {console.log('hello '+name)})"))

(.executeVoid hello-fn (into-array String ["world!"])) ;; output: hello world!

All kinds of JavaScript values are represented as org.graalvm.polyglot.Value objects by GraalJS. In the above example the (.eval ...) calling returns a executable polyglot.Value.

We can check if it is an executable by calling the .canExecute() method.

(.canExecute hello-fn) ;; true

We can invoke the executable by calling the .execute() method or the .executeVoid() method. Their difference is that latter one doesn't have a return value.

(.executeVoid hello-fn (into-array Object ["world"])) ;; output: hello world

(.executeVoid hello-fn (into-array Object ["graaljs"])) ;; output: hello graaljs

You can check if a polyglot.Value object is of a certain type by using methods starting with .is, and convert the Value object to native Java value with methods starting with .as. For example:

(def integer-one (.eval *context* "js" "1")) ;; #object[org.graalvm.polyglot.Value 0x3583d830 "1"]
(.isNumber integer-one) ;; true
(.asLong integer-one) ;; 1
(.isString integer-one) ;; false
(.asString integer-one) ;; ERROR: Unhandled java.lang.ClassCastException

To handle JavaScript objects, we have .newInstance() for instantiating an Object, .invokeMember() for calling a method, .getMemberKeys(), .getMember() and .putMember() for accessing properties of an object.

;; We can access top-level JavaScript variables using the (.getBindings *context* "js").
;; It returns a polyglot.Value object from which we can retrieve builtin
;;   JavaScript functions and objects.
(def Array (.getMember (.getBindings *context* "js") "Array"))

;; create an Array
(def arr (.newInstance Array (into-array Object [1 2 3])))

(print arr) ;; #object[org.graalvm.polyglot.Value 0x2dd585ca "(3)[1, 2, 3]"]

;; pop a value and cast it to Long
(.asLong (.invokeMember arr "pop" (into-array Object []))) ;; 3

(print arr) ;; #object[org.graalvm.polyglot.Value 0x27e1e162 (2)[1, 2]]

Working With JavaScript Libraries

GraalJS has an option to provide a require function, with which we can import CommonJS JavaScript modules. The option isn't enabled by default. To enable it, we need to change the definition of *context* to the following:

(defonce ^:dynamic *context*
  (-> (Context/newBuilder (into-array String ))
      (.allowExperimentalOptions true)
      (.options (HashMap.
                 {"js.commonjs-require" "true"
                  "js.commonjs-require-cwd" (str (System/getProperty "user.dir")
                                                 "/node_modules")}))
      (.allowIO true)
      (.build)))

Here we use as commonjs-require-cwd's value. It tells GraalJS to find JavaScript modules under the node_modules folder in the project root.

We can then install JavaScript libraries using npm under the project root. Here I use "luxon" as an example.

npm init
npm install luxon

We can then import the module by using require function.

(def luxon (.eval *context* "js" "require('luxon')"))

We can access the resulting module with the .getMember() method.

(def DateTime (.getMember luxon "DateTime"))

Now we have the DateTime class from the luxon library, let's try to turn it into something useful:

(defn now []
  (-> DateTime
      ;; DateTime.now() returns a DateTime object
      (.invokeMember "now" (into-array Object []))
      ;; We call the .toString method to convert the object
      ;;    into a JavaScript String
          (.invokeMember "toString" (into-array Object []))
      ;; then we convert the result into a Java String
          (.asString)))

;; Let's try to call the function

(now) ;; "2025-11-15T16:56:49.798+08:00"
(now) ;; "2025-11-15T16:57:01.961+08:00"

We wrapped the details of interop between Clojure and JavaScript in a Clojure function now. Now if we want to get the current time string from the luxon library, we can just call the now function. The interop is still something quite cumbersome to do, however. In this blog I will show you how to turn it into something way more concise using the macros and other facilities provided by Clojure. Here is a glimpse of it:

(js.. lux/DateTime now toString) ;; "2025-11-15T17:04:38.574+08:00"

Ease Things With Helper Functions, Macros and More

You must have noticed the definition of the now function in the previous example is quite clumsy. In ClojureScript we have the following things that can facilitate the interop between ClojureScript and JavaScript

We can require a js module just like a clojure namespace
A ClojureScript function is just a JavaScript function, we can call JavaScript functions from the ClojureScript side, or we can pass ClojureScript functions to the JavaScript side.
We have dot macros ( ., .. and .- ) and set! to easily access properites or methods of JavaScript objects.

To build something on the same level is probably very hard, however, to build a demonstration of something very similar is indeed very achievable.

Mapping between Clojure and Polyglot Values

We probably don't want to manually convert the result each time we get a value from the JavaScript side as we did in the previous examples. So we would like to put the actual JavaScript functions invoking logics into a wrapper and let the wrapper automatically convert the parameters and the return value for us. To make something like this, and since GraalJS represents each JavaScript value as a Polyglot Value, we first need to establish a mapping between Clojure types and Polyglot Types.

Primitive Types

Each time we call the .execute() or .invokeMember() method of the polyglot.Value class, GraalJS will convert the arguments using .asValue() method of Context class. However, we are going to wrap Clojure functions as Polyglot functions in the next section. As of now, we write a Clojure -> Polyglot mapping function only calling the .asValue() method.

(defn polyglotalize-clojure [value]
  (cond
    ;; https://www.graalvm.org/sdk/javadoc/org/graalvm/polyglot/Context.html#asValue(java.lang.Object)
    :else
    (.asValue *context* value)))

As for the mapping from polyglot.Value to Clojure values, we use the various checking and converting methods described before.

(defn clojurify-value [^org.graalvm.polyglot.Value value]
  (cond (.isHostObject value)
        (.asHostObject value)

        (.isBoolean value)
        (.asBoolean value)

        (.isNull value)
        nil

        (.isString value)
        (.asString value)

        (.isNumber value)
        (cond (.fitsInLong value)
              (.asLong value)

              (.fitsInDouble value)
              (.asDouble value))

        :else
        value))

Functions

GraalVM provides various Proxy objects that we can use to make Clojure objects accessible in the JavaScript environment. To wrap a function, we need to use ProxyExecutable.

(defn wrap-clojure-fn [f]
  (.asValue *context*
            (with-meta (reify org.graalvm.polyglot.proxy.ProxyExecutable
                         #_{:clj-kondo/ignore [:unused-binding]}
                         ;; we ignore `this` for now
                         (execute [this ^"[Lorg.graalvm.polyglot.Value;" values]
                           (polyglotalize-clojure (apply f (map clojurify-value values)))))
              {::raw-fn f})))

The function takes a Clojure function as an argument, returns a Polyglot executable that we can pass to the JavaScript environment.

In the function body, we use reify to instantiate an object implementing the ProxyExecutable interface. We implement the .execute() method by applying the clojurified arguments to the original Clojure function, and convert the return value back to a Polyglot value using the two functions we wrote in the previous section.

In case we want to turn the proxy object back into a clojure function (like when a JavaScript function returns the proxy object as is), we save the original Clojure function into the metadata of the proxy object using with-meta. In the final step, we turn it into a Polyglot Value using .asValue method from Context.

Wrapping functions from JavaScript follows a similar logic.

(defn wrap-polyglot-executable [^org.graalvm.polyglot.Value obj]
  (with-meta (fn [& args]
               (clojurify-value (.execute obj (into-array Object (map polyglotalize-clojure args)))))
    {::raw-value obj}))

Here, we also save a reference to the original JavaScript function in the metadata. However, it serves a much more important role: In JavaScript, a function is like any object, it can have all kinds of properties. Therefore, after wrapping a JavaScript function as a Clojure function, we may still need to access its other properties. To do this, we save the original function in the metadata and retrieve it if necessary.

With these two functions defined, we can then augmented our two mapping functions.

(defn polyglotalize-clojure [value]
  (cond (::raw-value (meta value))
        (::raw-value (meta value))

        (fn? value)
        (wrap-clojure-fn value)

        :else
        ;; https://www.graalvm.org/sdk/javadoc/org/graalvm/polyglot/Context.html#asValue(java.lang.Object)
        (.asValue *context* value)))

(defn clojurify-value [^org.graalvm.polyglot.Value value]
  (cond

    (.isProxyObject value)
    (let [prox-obj (.asProxyObject value)]
      (if (::raw-fn (meta prox-obj))
        (::raw-fn (meta prox-obj))
        prox-obj))

    ;;
    ;; ... omitted
    ;;

    (.canExecute value) 
    (wrap-polyglot-executable value)

    :else
    value))

With these two facilities created, we already achieve something very interesting.

(def hello (clojurify-value (.eval *context* "js" "(function (name){console.log(`hello ${name}`)})")))

(hello "world") ;; output: hello world
(hello "graaljs") ;; output: hello graaljs

(def to-array (clojurify-value
               (.eval *context* "js" "(function (...args){return Array.from(args);})")))

(to-array 1 2 3 4) ;; #object[org.graalvm.polyglot.Value 0x26e3da6b "(4)[1, 2, 3, 4]"]

(def join (clojurify-value
           (.eval *context* "js" "(function (s, ...args){return args.join(s);})")))

(join "," 1 2 3 4) ;; "1,2,3,4"

As you have seen, we can now call a JavaScript function just like a Clojure function. Return values of primitive types will also be automatically converted back to Clojure values.

We can also pass Clojure functions to the JavaScript side:

(def sum-term
  (clojurify-value
   (.eval *context* "js" "let sum = (term, a, b) => (a>b)? 0 : term(a) + sum(term, a+1,b); sum")))

;; (sum-integers a b) calculate the sum of integers from `a` to `b` (inclusive)
(def sum-integers (partial sum-term identity))
(sum-integers 0 10) ;; 55

;; (sum-cubes a b) calculates the sum of cubes of integers from `a` to `b` (inclusive)
(def sum-cubes (partial sum-term (fn [x] (* x x x))))
(sum-cubes 0 10) ;; 3025

Objects

Rougly similar to ClojureScript, We don't do mapping for objects other than those of primitives types and functions. However, in the clojurify-value function, we wrap all JavaScript functions into Clojure functions and save the reference in the metadata, and as I have explained there, a JavaScript function may have other properties we want to access. Thus, in each place where a Clojure function wrapping a JavaScript function can be taken as arguments, we cannot use methods from polyglot.Value. Instead, we define helper functions that will wrap the arguments if necessary and then call the target method.

(defn polyglot-value [obj]
  (or (::raw-value (meta obj))
      (and (instance? org.graalvm.polyglot.Value obj)
           obj)))

(defn- to-camel-style [s]
  (string/replace s #"-([a-z])" (fn [g]
                                  (.toUpperCase (second g)))))

(defmacro define-unwrap-executable-alias
  {:clj-kondo/lint-as 'clojure.core/declare}
  [name & args]
  (let [docstring? (string? (first args))
        docstring (when docstring? (first args))
        args (if docstring? (second args) (first args))
        obj 'obj
        [arglist [_ vararg]] (split-with (fn [x] (not (= x '&))) args)] 
    `(defn ~name {:doc ~docstring} [~obj ~@arglist ~@(if vararg `[& ~vararg] [])]
       (let [~obj (or (polyglot-value ~obj)
                      ~obj)]
         (~(symbol (str "." (to-camel-style (str name))))
          ~obj 
          ~@arglist
          ~@(if vararg
              [`(into-array Object ~vararg)]
              []))))))

(define-unwrap-executable-alias get-meta-object)
(define-unwrap-executable-alias is-meta-object)
(define-unwrap-executable-alias get-meta-qualified-name)
(define-unwrap-executable-alias has-meta-parents)
(define-unwrap-executable-alias has-array-elements)
(define-unwrap-executable-alias get-meta-parents)
(define-unwrap-executable-alias get-member [^String identifier])
(define-unwrap-executable-alias put-member [^String identifier ^Object value])
(define-unwrap-executable-alias get-member-keys)
(define-unwrap-executable-alias new-instance [& args])
(define-unwrap-executable-alias can-invoke-member [^String s])
(define-unwrap-executable-alias invoke-member [^String method & args])
(define-unwrap-executable-alias can-instantiate)
(define-unwrap-executable-alias canExecute)
(define-unwrap-executable-alias execute [& args])
(define-unwrap-executable-alias executeVoid [& args])

We wrote a macro for this purpose. The macro takes a function name and a parameter list as arguments and defines a function with the name and parameters. The function defined by the macro retrieves the reference from the metadata if necessary, then calls a method by the name converted from the function name and with arguments from the parameter list.

One nice bonus is that the generated functions assembles all the variadic arguments into an Object[], saving us from calling (into-arry Object) manually if we need to call a method with variadic arguments.

Previously we need to do this:

(.newInstance (.eval *context* "js" "Array") (into-array Object [1 2 3]))
;; #object[org.graalvm.polyglot.Value 0x65b337ef "(3)[1, 2, 3]"]

Now we just need to do this:

(new-instance (.eval *context* "js" "Array") 1 2 3)
;; #object[org.graalvm.polyglot.Value 0xfdabe76 "(3)[1, 2, 3]"]

Dot Macros and `set!`

In ClojureScript we have dots special forms or macros like ., .- and .. for accessing properties or calling methods of JavaScript objects.

We can relatively easily implement them using macros.

There are also (.method obj) (.-property obj) as shorthands for (. obj method) and (.- obj property) in ClojureScript. However, implementing them would be really difficult if not impossible.

(defmacro js.
  {:clj-kondo/ignore [:unresolved-symbol :type-mismatch]}
  [obj method & args]
  `(clojurify-value
    (apply invoke-member ~obj ~(str method)
           ;; evaluate args before passing them to polyglotalize-clojure
           (map polyglotalize-clojure (list ~@args)))))


(defmacro js.-
  {:clj-kondo/ignore [:unresolved-symbol :type-mismatch]}
  [obj field]
  `(#'clojurify-value (get-member ~obj ~(str field))))

The invoke-member and get-member helper functions are defined in the previous section.

With these two defined, we can write the more complicated macro js.. based on them.

(defmacro js..
  {:clj-kondo/ignore [:unresolved-symbol :type-mismatch]}
  [obj & args]
  (if (empty? args)
    obj
    (let [curr# (first args)
          rest# (rest args)]
      `(js.. ~(cond (seq? curr#)
                    `(js. ~obj ~(first curr#) ~@(rest curr#))

                    (.startsWith (str curr#)
                                 "-")
                    `(js.- ~obj ~(subs (str curr#) 1))

                    :else
                    `(js. ~obj ~curr#))
         ~@rest#))))

Finally, we will implement the set! macro.

(defmacro js-set! [dot-form value]
  (assert (seq? dot-form) "First argument must be in the form of `(js.. obj -field)` or (js.- obj field)")
  (let [[op & args] dot-form]
    (assert (or (= op 'js..)
                (= op 'js.-))
            "First argument to js-set! must start with either `js..` or `js.-`")
    (let [remove-hyphen (= op 'js..)
          lst (last args)
          last-removed (drop-last (into [op] args))]
      `(put-member ~(if (= (count last-removed) 2)
                      (second last-removed)
                      last-removed)
                   ~(if remove-hyphen
                      (subs (str lst) 1)
                      (str lst))
                   ~value))))

Let's go back to the luxon example mentioned in the beginning of this blog and check what we can do with these newly defined tools.

(def luxon (.eval *context* "js" "require('luxon')"))

(js.. luxon -DateTime now toString) ;; "2025-11-14T16:48:11.324+08:00"

Compare it to the snippet I showed at the end of the first section:

(js.. lux/DateTime now toString)

The only thing lacking is a require mechanism, which is what we are going to implement in the next section.

`require` command

On the JavaScript side, the require() function returns an object from which we can access its exported variables or functions.

On the Clojure side, we can dynamically create a namespace with the create-ns function. After that we can make all the variables from the module object accessible in the newly created namespace with the intern function.

(defn- require-module [name]
  (-> *context*
      (.eval "js"
             (str "require('" name "')"))))

(defn- parse-flags [args]
  (loop [args (lazy-seq args)
         result (hash-map)]
    (if (empty? args)
      result
      (let [curr (first args)
            rst (rest args)]
        (if (or (keyword? (first rst))
                (empty? rst))
          (recur rst (assoc result curr true))
          (recur (rest rst)
                 (assoc result curr (first rst))))))))

(defn- normalize-module-name [name]
  (s/replace (str name) #"/" "."))

(defn require-js
  {:clj-kondo/lint-as 'clojure.core/require}
  [[module-name & flags] & coll]
  (let [flag-map (parse-flags flags)
        module (require-module module-name)
        alias-name (:as flag-map)
        qualified-module-name (symbol (str "js4clj.modules." (normalize-module-name module-name)))]
    (create-ns qualified-module-name)
    (doseq [k (.getMemberKeys module)]
      (intern qualified-module-name
              (symbol k)
              (clojurify-value (.getMember module k))))
    (when alias-name
      (alias alias-name qualified-module-name)))
  (when (seq coll)
    (apply require-js coll)))

(require-js '[luxon :as lux]) is now all we need to require a JavaScript module.

(require-js '[luxon :as lux])

(js.. lux/DateTime now toString) ;; "2025-11-14T17:08:40.045+08:00"

Let's try some more examples:

(js.. lux/DateTime (fromISO "2017-05-15T08:30:00") -year) ;; 2017

;; or write it as
(-> lux/DateTime
    (js. fromISO "2017-05-15T08:30:00")
    (js.- year)) ;; 2017

(let [now (js. lux/DateTime now)
      later (js. lux/DateTime local 2026 10 12)
      i (js. lux/Interval fromDateTimes now later)]
  (js. i length "years")) ;; 0.904136850298072

Bonus: Special `js` namespace

ClojureScript provides us a special js namespace, from where we can use various JavaScript global objects. We can also implement something like that.

(def ^:dynamic *no-clojurify* false)

(defn- define-builtin [ns primitive & [alias]]
  (intern ns (if alias (symbol alias) (symbol primitive))
          ((if *no-clojurify* identity clojurify-value)
           (.eval *context* "js" primitive))))

(defmacro define-builtins
  {:clj-kondo/lint-as 'clojure.core/declare}
  [ns & primitives]
  (create-ns ns)
  `(doseq [primitive# '~primitives]
     (define-builtin '~ns (str primitive#))))

;; In cljs there is also a js/undefined
;;	in which (= nil js/undefined) but we can't mimic it.
;; Still, we need a js/undefined in case we need to do some
;; 	very specific interop.
(declare undefined)
(with-bindings {#'*no-clojurify* true}
  (define-builtin 'js "undefined" "undefined"))

#_{:clojure-lsp/ignore [:clojure-lsp/unused-public-var]}
(define-builtins js
  globalThis
  Infinity
  NaN
  Object
  Function
  Boolean
  Symbol
  Error
  Number
  BigInt
  Math
  Date
  String
  Array
  Map
  Set
  WeakMap
  WeakSet
  JSON
  ArrayBuffer
  Promise
  console)

We took a special handling of js/undefined (note when we clojurify JavaScript values, we turn both null and undefined into nil), since a direct equivalent of undefined in JavaScript may be needed for some interops. However, js/undefined In ClojureScript has some special properties we can't replicate, most notably, (nil? js/undefined) and (= js/undefined nil) results in true in ClojureScript.

Limitations

Functionalities specific to an environment

JavaScript packages are often written under the assumption that, the code will either run on a Browser or a node.js environment. Unfortunately, GraalJS only implements the ECMAScript specification, which means we have neither functions specific to node.js nor functions specific to a browser.

For example, we don't have WebWorker api from the browser, nor process, fs api from node.js.

Multithreading and the `js` namespace

When writing programs in Java, we usually use blocking operations and multithreading. However, polyglot.Context is not thread-safe. It isn't a problem in itself, since we can spin up multiple contexts. However, variables in js refer to variables in a specific context. Thus, if we want to use multiple contexts, we cannot refer to variables in the js namespace with the current settings. We may be able to mitigate or solve this problem with dynamic bindings or using a dedicated thread for JavaScript operations.

Shorthands for dot macros

We have already talked about it in the Dot Macros section. In ClojureScript we can (ClassName.) for instantiate an instance or (.method obj) for invoking an method. Implementing them would be really hard if not impossible.

Importing ECMAScript Modules

The require-js function can only import CommonJS modules. More and more projects are choosing ECMAScript modules over CommonJS modules these days. However, implementing an importing mechanism for ECMAScript modules is entirely feasible. GraalJS provides a js.esm-eval-returns-exports option, with this option enabled, we can import a ECMAScript module by loading the source file. However, it will take some time to write support for things like exports fields in package.json.

Using JavaScript array in Clojure

In ClojureScript, many times we can use a JavaScript array just like a ClojureScript vector (not vice versa though). We haven't implement something similar to this.

;; ClojureScript
(map (fn [x] (* x 2)) #js [1 2 3])
;; (2 4 6)

To Be Continue…

Despite the limitations, I still believe this approach is something worth exploring. I'm planning on making an isomorphic React demonstration with Server Side Rendering and Client Side Rehydration using only a thin wrapper over React and React DOM Server (instead of reimplementing the SSR logics on the JVM). The code presented here is also expanded and refined when I'm writing the blog, and the code is open sourced at imakira/js4clj.

Build a ClojureScript Application Running on Node Using Nix

2025-11-03T17:25:27+08:00

To build a ClojureScript application, we need to pull dependencies from two package managers. That is, JavaScript packages from npm and Clojure packages from deps.edn. After pulling the dependencies, we can then let shadow-cljs compiles the ClojureScript files into a single javascript and make the result a npm package. In this post, we rely on nixpkgs's builtin fetchNpmDeps and buildNpmPackage for the npm side, and clj-nix for the nix side.

changelog Jan 17, 2026: use a new method to build the nix package, supports git repos, reduces output size.

Prerequisites

I will skip the details that are not unique to Nix. The following contents assume we already have a working shadow-cljs project that can produce a node.js target when running npm run release. Which is basically:

a :node-script target in shadow-cljs.edn, with :main function specified
a release script in package.json, most probably shadow-cljs release script
an entry script specified in bin in package.json.

Prefetch and generate lock file for dependencies

During the build phase of nix package, the process cannot perform any network request, as that will defeat the whole point of determinism. The common practice is to use a lock file. Which is essentially a recipe of all the necessary resources (and their checksums) for the building process. We can then prefetch all the resources into the nix store and tell the building process where to find the necessary resources during the actual building.

On the npm side, we do it by running the following command. It will output a sha256 code, we save it for later.

nix run nixpkgs#prefetch-npm-deps package-lock.json

On the Clojure side, we execute the following command. It will generate a deps-lock.json file. We will refer it in the flake.nix.

nix run github:jlesquembre/clj-nix#deps-lock

Build with shadow-cljs and `mkCljLib`

We need to add clj-nix's overlays to our flake.nix to be able to use mkCljLib.

pkgs = import nixpkgs {
  inherit system;
  overlays = [
    clj-nix.overlays.default
  ];
};

First, we create a node_modules derivative which we will use later.

deps-hash = "deps-hash";

npm-deps = pkgs.buildNpmPackage(finalAttrs: {
  src = self;
  pname = "package-npm-deps";
  version = "0.0";
  dontNpmBuild = true;
  npmDepsHash = deps-hash;
  installPhase = ''
  mkdir $out
  cp -r ./node_modules $out/node_modules
  '';
});

We will use mkCljLib to setup Clojure dependencies for us, while we copy JavaScript dependencies from the earlier step manually.

build = pkgs.mkCljLib {
  projectSrc = self;
  name = "espoir";
  buildCommand = "
  # copy node_modules from earlier step to build directory
  cp -r ${npm-deps}/node_modules ./node_modules
  ${pkgs.nodejs}/bin/npm run release
  ";
  installPhase = ''
  mkdir -p $out
  cp -R * $out/
  '';
};

In the buildCommand, we setup the JavaScript dependencies, and call npm run release which in turn calls shadow-cljs to build the project.

In installPhase, we override the install process provided by mkCljLib. Instead, we simply use all the files in the build directory as output.

Package results as a npm package

We can directly feed output from the earlier example to builNpmPackage. Since we already build the package, we will set dontNpmBuild = true;.

The install process provided by buildNpmPackage will package necessary dependencies and generate an executable calling the entry script.

packages.default = pkgs.buildNpmPackage {
  pname = "espoir";
  src = build;
  dontNpmBuild = true;
  version = "0.0.1";
  npmDepsHash = deps-hash;
};

Tips

Check imakira/espoir/blob/main/flake.nix for a working example.

Develop and Build a Common Lisp Project using Nix

2025-10-27T17:50:17+08:00

I recently tried to build a Common Lisp project using Nix and found it is quite easy with just the buildASDFSystem function in nixpkgs and ASDF alone. I will share how I have done it here in case someone else finds it useful.

Simple Configuration When Developing

On the Nix we will have something like this:

# flake.nix
{
  description = "";
  inputs.flake-utils.url = "github:numtide/flake-utils";
  inputs.nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
  outputs = { self, flake-utils, nixpkgs }:
    flake-utils.lib.eachDefaultSystem (system:
      let pkgs = nixpkgs.legacyPackages.${system};
      in rec {
        packages.default = pkgs.sbcl.buildASDFSystem {
          pname = "proj-name";
          version = "0.1";
          src = self;
          lispLibs = with pkgs.sbclPackages; [
            alexandria
            # lisp packages in nixpkgs go here
          ];
          nativeLibs = [
            # native libs go here
          ];
        };
      }
    );
}

On the Lisp side we will have an asd file

;; proj-name.asd
(require 'asdf)
(asdf:defsystem "proj-name"
  :depends-on (#:alexandria)
  :components ((:file "main"))) ;; we will have a main.lisp file

With these two files we can then start developing the project with the following steps

Enter nix develop environment by executing nix develop . in the directory the project.
Launch Emacs inside the developing environment.
Launch sly (or slime) in Emacs, and load the asd file by sly-compile-and-load-file.
Execute (asdf:load-system "proj-name") in the sly repl.
Enjoy!

Building an Executable

To build an executable we need a few more snippets on the Nix side

#...

packages.default = pkgs.sbcl.buildASDFSystem {
  # ...
  # other code is omitted here
  lispLibs = with pkgs.sbclPackages; [
    alexandria
    # lisp packages in nixpkgs go here
  ];

  nativeBuildInputs = [
    pkgs.makeWrapper
  ];

  buildScript = pkgs.writeText "build-awesomes" ''
    (require 'asdf)
    (asdf:load-system "proj-name")
    (sb-ext:save-lisp-and-die
                "proj-name"
                :executable t
                #+sb-core-compression :compression
                #+sb-core-compression t
                ;; assume we have the `main' function defined and exported in the main.lisp file
                :toplevel #'main:main) 
  '';

  installPhase =   ''
    runHook preInstall
    mkdir -p $out/bin
    cp proj-name $out/bin

    # make sure the executable can find dynamically linked libraries
    wrapProgram $out/bin/proj-name \
                --prefix LD_LIBRARY_PATH : $LD_LIBRARY_PATH
    runHook postInstall
  '';
};

When we execute nix build . in the project directory, lisp scripts in buildScript will be executed and generates a binary file proj-name. The binary file will then be copied into $out/bin directory by the scripts inside installPhase. After the nix build . finished, we can find the executable in the result/bin/ directory

We can also use nix run . to run the result executable directly.

Limitations of This Method and Other Notes

The biggest limitation of this solution may be you need to restart the REPL (or even the Emacs launched inside the develop environment) every time you add a package into the flake.nix.

You can find the lisp section of the nixpkgs documentation here. packages.nix in the nixpkgs also has plenty lisp project definitions we can take references from.

I have a little project built this way and it runs on github actions simply by using nix run ., you can also check that.

Demonstration

2024-10-13T22:15:21+08:00

Code Blocks

Inline Code Block

Text around (uix.dom/create-root (js/document.getElementById "root")) the inline code block.

Code Blocks

Java

public static int fib(int n) { 
    if (n <= 1) {
        return n;
    }
    return fib(n - 1) + fib(n - 2);
}

Clojure

(defui app [{:keys [initial-route]}]
  (let [[show-header? set-header!]
        (use-state
         (some #(= % initial-route)
               ["/" "/home.html" "/template.html"
                "/index.html"]))]
    (context-binding [*header-context* [show-header? set-header!]]
      ($ router/router {:routes routes :initial-route initial-route}
         ($ main {})))))

Emacs Lisp

(save-excursion                 
    (goto-char (point-min))

(with-current-buffer (current-buffer)
  (let ((ids (org-map-entries (lambda ()
                                (org-entry-get nil "custom_id")))))
    (org-map-entries (lambda ()
                       (when (not (org-entry-get nil "custom_id"))
                         (let* ((candidate-id (concat "blog_" (url-encode-url (nth 4 (org-heading-components)))))
                                (duplicates (cl-count candidate-id ids)))
                           (org-entry-put nil "custom_id" (concat candidate-id
                                                                  (prin1-to-string (+ 1 duplicates))))))
                       (setq ids (cons (org-entry-get nil "custom_id")
                                       ids))))))

H2 Sample Text

H3 Sample Text Sample Text

Some text in between

H4 Sample Text Sample Text

Some text in between

H5 Sample Text Sample Text

Some text in between

Common Elements

italic
bold
underline
verbatim
code
~~strike-through~~
Horizontal Rule
code

Other Elements

Table

Name	Phone	Age
Peter	1234	17
Anna	4321	25

Reference

Everything should be made as simple as possible, but not any simpler – Albert Einstein

Unordered List

Item 1
Item 2
- Level 2
  - Level 3
    - Level 4
  - Another Mark
Item 3

Ordered List

Item 1
Item 2
Item 3
Item 4

Description List

Name

Description

Nested: Nested Description

Name

Description

Sample Image

Figure 1: This is an image

Figure 2: sample high resolution vertical image

Figure 3: sample high resolution horizontal iamge

Verbatim

Inline CLJC Code (OrgX)

You can embedded Clojure code inside a blog file using #+begin_orgx blocks.

Enable this feature first in the org metadata:

#+ORGX: true

With the following snippet embedded in a org file.

#+begin_orgx
  ;; You can style it using tailwindcss
  ($ :button {:class "bg-sky-600 text-neutral-50 py-1 px-2 rounded-lg" :on-click (fn [& _] #?(:cljs (js/alert "clicked!")))} "Click Me")
#+end_orgx

We can get a clickable button in the generated page:

Since the code is in CLJC, this feature works very well with static page generation / server side rendering. However, you must wrap plaform specified code in read macros like we do in a normal CLJC file.

We can access the blog page's meta data using post-props variable.

#+begin_orgx
($ :div {:class "bg-stone-50 pl-4 py-2 border-l-3 border-sky-500"} (str (keys post-props)))
#+end_orgx

(:blog/orgx :blog/tags :blog/unlisted :blog/title :blog/show-toc? :blog/file-path :blog/author :blog/email :blog/description :blog/id :blog/category :blog/language :blog/published-date :blog/content :blog/orgx-require :blog/modified-date)

Inline Clojure Snippet

We can @@orgx:($ :span.bg-cyan-50.mt-2.pl-2.py-1.border-l-3.border-sky-500 "also have inline Clojure snippets")@@ like this.

Will be render as

We can also have inline Clojure snippets like this.

Using Other OrgX files as components

Like with MDX, we can use other orgx files as components.

First we make a note.org file with the following as contents, note the #+UNLISTED property.

#+ORGX: true
#+UNLISTED: true
#+begin_orgx
($ :div
    ($ :div {:class "bg-stone-50 pl-4 py-2 border-l-3 border-rose-500"}
      ($ :div {:class "font-semibold mb-1 text-neutral-600"} "TIP")
      ($ :div (:children post-props))))
#+end_orgx

When we want to use this OrgX file as a components, we need to add a require declaration first.

#+ORGX_REQUIRE: [[orgx.note :as note]]

Then we could use it like this

#+begin_orgx
($ note/component  "This is a note")
#+end_orgx

It will be rendered as:

TIP

This is a note

Builtin Components

Simple Remarks

It has several builtin components, notebly, the following snippet:

#+begin_orgx
($ info "This is an info")
($ note "This is a note")
($ warn "This is a warn")
($ error "This is an error")
#+end_orgx

Will be rendered as:

This is an info

This is a note

This is a warn

This is an error

Tabs

tab_demo.org:

#+attr_orgx_defui: true
#+begin_orgx_code_clj
#+begin_src clojure
(defui tabs [{:keys [tab-list default-table class]}]
  (let [[selected-tab set-selected-tab!] (use-state (or default-table
                                                        (:name (first tab-list))))]
    ($ :div.my-4.relative.border-sky-300.border-l-2.border-l-neutral-100 {:class class}
       ($ :div.my-0.flex.relative.bg-neutral-100
          (map (fn [{:keys [name]}]
                 ($ :button.font-medium.text-neutral-700.bg-neutral-50.py-1.px-2.border-t-2.border-neutral-50.min-w-28.bg-neutral-50.border-t-neutral-100
                    {:key name
                     :class (when (= name selected-tab)
                              " text-sky-800 border-sky-400 bg-sky-100 border-t-sky-400")
                     :on-click (fn []
                                 #?(:cljs
                                    (set-selected-tab! name)))}
                    name))
               tab-list))
       ($ :div.my-0.bg-neutral-50.overflow-hidden.px-2.h-full
          (:content (first (filter (fn [{:keys [name]}]
                                     (= name selected-tab))
                                   tab-list)))))))

#+end_src
#+end_orgx_code_clj

#+attr_orgx_defui: true
#+begin_orgx_code_org
#+begin_example
Well we can't display the contents recurisvely
#+end_example
#+end_orgx_code_org


#+begin_orgx
($ tabs {:tab-list [{:name "tab_demo.org" :content ($ code_org)} {:name "tabs.clj" :content ($ code_clj)}]})
#+end_orgx

tabs.clj:

(defui tabs [{:keys [tab-list default-table class]}]
  (let [[selected-tab set-selected-tab!] (use-state (or default-table
                                                        (:name (first tab-list))))]
    ($ :div.my-4.relative.border-sky-300.border-l-2.border-l-neutral-100 {:class class}
       ($ :div.my-0.flex.relative.bg-neutral-100
          (map (fn [{:keys [name]}]
                 ($ :button.font-medium.text-neutral-700.bg-neutral-50.py-1.px-2.border-t-2.border-neutral-50.min-w-28.bg-neutral-50.border-t-neutral-100
                    {:key name
                     :class (when (= name selected-tab)
                              " text-sky-800 border-sky-400 bg-sky-100 border-t-sky-400")
                     :on-click (fn []
                                 #?(:cljs
                                    (set-selected-tab! name)))}
                    name))
               tab-list))
       ($ :div.my-0.bg-neutral-50.overflow-hidden.px-2.h-full
          (:content (first (filter (fn [{:keys [name]}]
                                     (= name selected-tab))
                                   tab-list)))))))

Split Layout

Split layout lets you show two things side by side:

#+attr_orgx_defui: true
#+begin_orgx_split_1
#+begin_src clojure
  ($ :button {:class "bg-sky-600 text-neutral-50 py-1 px-2 rounded-lg"
              :on-click (fn [& _]
                          #?(:cljs (js/alert "clicked!")))}
     "Click Me")
#+end_src
#+end_orgx_split_1

#+attr_orgx_defui: true
#+begin_orgx_split_2
#+begin_orgx
  ($ :button {:class "bg-sky-600 text-neutral-50 py-1 px-2 rounded-lg"
              :on-click (fn [& _]
                          #?(:cljs (js/alert "clicked!")))}
     "Click Me")
#+end_orgx
#+end_orgx_split_2

#+begin_orgx
($ split-layout
($ tabs {:tab-list [{:name "button" :content ($ split_1)}]})
($ tabs {:tab-list [{:name "showcase" :content ($ split_2)}]}))
#+end_orgx

Will be rendered as:

button:

($ :button {:class "bg-sky-600 text-neutral-50 py-1 px-2 rounded-lg"
            :on-click (fn [& _]
                        #?(:cljs (js/alert "clicked!")))}
   "Click Me")

showcase:

Showcase

Showcase is a simple wrapper over split-layout.

showcase demo:

#+begin_orgx
($ showcase
  ($ tabs {:tab-list [{:name "button" :content ($ split_1)}]})
  ($ split_2))
#+end_orgx

Result:

Use uix components with org-mode markups

Hello

Coruscation.net

About Dynamic Adding to Classpath in Clojure

Use Builtin clojure.core/add-classpath

Use add-classpath from pomegranate

Create a DynamicClassLoader When There isn't One

When Using kaocha

Pitfall When Using a Threadpool

A Few More Words

Links

Something Like MDX but with Clojure and Org-Mode for My Personal Blog: Part I

How OrgX Works

Basic Usage

Toplevel Clojure Code

Import Modules

Access Component Properties

Use Other OrgX Files as Components

Use OrgX With Native Org Syntax

Use Components

Build Components

Inline OrgX with Macros

Builtin Components

Simple Notice Blocks

Tabs

Split Layout

Showcase

Conclusions

Caveats

Future Plans

Watching Files with java.nio.file.WatchService and Clojure

The Problem

The Workaround

How is it Handled by Other Projects?

chokidar

inotify-tools

Conclusion

My Experience with lsp-bridge

Basic Setup

Configuration

Keymapping

a Little Hack (minimum popup width)

flymake

Workspace Management

Working with Java

Working with Clojure and Cider

Conclusion

Experiment with GraalVM, Clojure, and JavaScript

Basic Setup and a Hello World Program

Working With JavaScript Libraries

Ease Things With Helper Functions, Macros and More

Mapping between Clojure and Polyglot Values

Primitive Types

Functions

Objects

Dot Macros and set!

require command

Bonus: Special js namespace

Limitations

Functionalities specific to an environment

Multithreading and the js namespace

Shorthands for dot macros

Importing ECMAScript Modules

Using JavaScript array in Clojure

To Be Continue…

Build a ClojureScript Application Running on Node Using Nix

Prerequisites

Prefetch and generate lock file for dependencies

Build with shadow-cljs and mkCljLib

Package results as a npm package

Tips

Develop and Build a Common Lisp Project using Nix

Simple Configuration When Developing

Building an Executable

Limitations of This Method and Other Notes

Demonstration

Code Blocks

Inline Code Block

Code Blocks

H2 Sample Text

H3 Sample Text Sample Text

H4 Sample Text Sample Text

Use Builtin `clojure.core/add-classpath`

Use `add-classpath` from `pomegranate`

Create a `DynamicClassLoader` When There isn't One

When Using `kaocha`

Dot Macros and `set!`

`require` command

Bonus: Special `js` namespace

Multithreading and the `js` namespace

Build with shadow-cljs and `mkCljLib`