Rum

Rum is a client/server library for HTML UI. Its behavior depends on the language used:

• ClojureScript: It acts as a React wrapper.
• Clojure: It functions as a static HTML generator.

Key characteristics include:

• Decomplected: It is a library, not a framework. You can use only the parts you need or combine it with other frameworks.
• No enforced state model: Unlike other frameworks, Rum does not dictate how to store state. It is compatible with atoms, persistent data structures, DataScript, JavaScript objects, and more.
• Extensible: It provides a stable API for building custom component behaviors.
• Minimal: The codebase is small (~900 lines), making it easy to understand.

In Rum, the performance of the = operator depends on whether the data structures share identity (structural sharing).

1. Fast Equality (Identity Check): If two values are the same object in memory, = performs an identical? check and returns true immediately. This is common when using central data stores where subtrees are passed down.
2. Slow Equality (Deep Equals): If two values are created from scratch (e.g., {:key :value} vs {:key :value}), = must perform a deep equality check, walking the entire data structure.

Performance Note: Because Rum pre-compiles Hiccup into React calls via the defc macro, the cost of re-running a component is lower than in libraries like Reagent. Consequently, the performance benefit of memoization via rum/static may be less significant in Rum than in other ClojureScript React wrappers.

A Rum component consists of a render function, mixins, an internal state map, and a React component. You can use rum.core/defcs to access the state map in your render function.

Mixins are maps of lifecycle callbacks that receive state and return a new state. Common callbacks include:

• :init: (state, props) -> state
• :will-mount: (state) -> state
• :did-mount: (state) -> state
• :should-update: (old-state, state) -> boolean
• :will-unmount: (state) -> state
• :did-update: (state) -> state

To trigger a manual update from a mixin, access the React component via (:rum/react-component state) and call rum.core/request-render on it.

(rum/defcs time-label
  < { :will-mount (fn [state]
                    (assoc state ::time (js/Date.))) }
  [state label]
  [:div label ": " (str (::time state))])

If a component only accepts immutable data, use the rum.core/static mixin. This tells Rum to check if the component's arguments have changed (using Clojure's -equiv) and skip re-rendering if they are the same.

Warning: Do not pass mutable references as arguments to static components, as this will bypass the optimization and cause bugs.

(rum/defc label < rum/static [n text]
  [:.label (replicate n text)])

To maintain mutable data internal to a component, use the rum.core/local mixin and the rum.core/defcs macro.

1. Use rum.core/defcs (which passes the component's state as the first argument to the render function).
2. Use rum.core/local to inject an atom into the state.
3. Extract the atom from the state using the key provided in the mixin.

(rum/defcs stateful < (rum/local 0 ::key) 
  [state label]
  (let [local-atom (::key state)]
    [:div { :on-click (fn [_] (swap! local-atom inc)) }
      label ": " @local-atom]))

(rum/mount (stateful "Click count") js/document.body)

To make a component automatically re-render when an atom changes, use the rum.core/reactive mixin and the rum.core/react function instead of deref inside the component body.

(def count (atom 0))

(rum/defc counter < rum/reactive []
  [:div { :on-click (fn [_] (swap! count inc)) }
    "Clicks: " (rum/react count)])

(rum/mount (counter) js/document.body)

Rum provides React Hooks for use within defc components. To use hooks, you must follow these rules:

1. Use defc components: Hooks only work in function-based components.
2. Avoid Mixins with Hooks: Do not use both hooks and mixins in the same component. If you use a mixin, Rum generates a class-based component, which causes React to throw an exception when hooks are present.
3. Use rum/static for memoization: If you want to use hooks in a memoized component, use the rum/static mixin. This tells Rum to generate a function-based component wrapped in React.memo instead of a class-based component.

Summary of rum/static: When used as the only mixin in a defc, it enables component memoization based on arguments by generating a React.memo wrapper.

Rum supports SSR on the JVM. When running on a server (clj/cljc), Rum acts as a template engine and does not require JavaScript.

1. Server side: Use rum.core/render-html to generate an HTML string from a component.
2. Client side: Use rum.core/hydrate to attach React to the existing server-rendered DOM.
3. Static only: If you don't want React interactivity, use rum.core/render-static-markup.

;; On server
(rum/render-html (my-comp "hello"))

;; On client
(rum/hydrate (my-comp "hello") js/document.body)

When using code-splitting, your HTML must include the shared base chunk (cljs_base.js) before the specific entry point chunks. The order should be:

1. The container element.
2. The shared base chunk.
3. The main entry point chunk.

<div id="root"></div>
<script src="/out/cljs_base.js"></script>
<script src="/out/core.js"></script>

To add Rum to your ClojureScript project, add the following dependency to your project.clj file:

[rum "0.12.11"]