Cherry

When using advanced compilation, cherry's output might not be able to find certain CLJS functions unless they are explicitly preserved. Use the preserve-ns macro to make an entire namespace available as globals.

If you do not want to preserve an entire namespace, you can instead use the ^:export metadata on specific functions or values within your CLJS namespace to make them available:

(defn ^:export foo [])

(cherry/preserve-ns 'cljs.core)

To prevent users from accidentally importing unstable internal names that change with every build, Cherry uses a facade pattern:

• Internal Module: The actual definitions and ~916 internal names are moved to an internal module (e.g., lib/internal/cljs.core.js).
• Public Facade: lib/cljs.core.js acts as a facade that re-exports only the stable public API.
• Compatibility: User-compiled code continues to import 'cljs.core.js' unchanged. Bundlers like esbuild can shake through the facade to the internal implementation with zero overhead.

Cherry uses a specialized production transform to re-massage the Closure output of cljs.core.js. This allows bundlers like esbuild to effectively tree-shake the core library, which is otherwise difficult to shake due to its reliance on a global $APP object and side-effect-heavy property assignments.

Key Benefits

• Drastic Bundle Reduction: A bare import of cljs.core.js can be reduced from ~364 KB to ~2.0 KB.
• Granular Imports: Importing specific functions (e.g., import { str }) results in much smaller bundles (e.g., ~133 KB) compared to the full core.
• Wire Parity with Vanilla CLJS: While vanilla CLJS with advanced optimizations is smaller raw, the tree-shaken Cherry approach achieves near-parity in compressed (gzip/brotli) sizes, while keeping user builds free from the Closure compiler.

To avoid duplicating CLI logic (like argument validation, error reporting, and command scaffolding), Cherry uses a shared CLI namespace (squint.internal.cli-common) parameterized by a dialect map.

When adding new CLI features, they should be implemented in the shared squint namespace and exposed to Cherry by updating its dialect map. This ensures fixes and features land in one place.

;; Example of the dialect map structure used to parameterize the shared CLI
{:prog "cherry" 
 :log-prefix "[cherry]" 
 :config-file "cherry.edn" 
 :compile-file cherry.compiler.node/compile-file 
 :resolve-ns ... 
 :commands #{:run :compile :watch :eval}}

To run the demonstration project that uses Cherry with Vite.js, install the dependencies using npm and then use the bb (Babashka) task runner to start the development server.

To see changes reflected in the browser, edit the cherry.cljs file.

npm install
bb dev

When saving .cljs or .cljc files, Cherry hot-swaps the module in the browser without a full page reload. You can execute code specifically before or after this swap using metadata tags on functions:

• ^:dev/before-load: Runs before the new code is loaded.
• ^:dev/after-load: Runs after the new code is loaded.

This is useful for re-initializing state or re-rendering components after a code change.

(defn ^:dev/after-load re-render []
  (swap! store identity))

Cherry provides support for a browser-based REPL integrated with Vite's Hot Module Replacement (HMR) via WebSockets. This setup allows for live evaluation in the browser.

Cherry's vite.js implementation uses a dialect adapter that connects to squint's makeVitePlugin. This enables a development workflow featuring:

• A live Vite dev server
• Browser evaluation over nREPL
• Hot-reload hooks

To run the Replicant tic-tac-toe demo locally, which uses cherry to compile replicant and is served via vite with the cherry plugin, follow these steps:

1. Install dependencies using npm install.
2. Start the development server with npm run dev.

This setup includes a browser REPL for interactive development.