devcards-loader

A tiny library hack to load bhauman/devcards with only the marked and highlight.js npm packages required as external dependencies.

Rationale

bhauman/devcards cannot be loaded directly as a library into a cljs project (see bhauman/devcards#168) due to internal npm package naming conventions introduced earlier in its development, before npm package integration with shadow-cljs and ClojureScript were the norm.

This library creates a tiny layer in front of devcards so that it can be loaded in a cljs project as usual, provided that its two required dependencies were made available via npm.

Usage with shadow-cljs

Add devcards-loader in your :deps deps.edn file:

{:deps {ikappaki/devcards-loader {:git/url "https://github.com/ikappaki/devcards-loader"
                                  :git/tag "v0.1.0"
                                  :git/sha "b6a4abda4994838ae3e4d556465e3445ec89e95b"}
        ;; ...
        }
 ;; ...
 }

This brings in bhauman/devcards; you can refer to it as normal from your app.

Install the markedjs/marked v3.x and highlight.js (tested with v11.x) npm packages:

npm install marked@"<4.0.0"

npm install highlight.js

Optionally, add a new :devcards test build in your shadow-cljs.edn file to load all namespaces ending in -cards as devcards:

{:deps true          ;; delegate deps resolution to deps.edn file.

 ;; ...

 :builds
 {;; ...
  :devcards
  {:target           :browser-test
   :ns-regexp        "-cards$"            ;; load all namespaces ending in "-cards$".
   :test-dir         "out/devcards"
   :runner-ns        devcards-toc         ;; call custom fn devcards-toc/init.
   :compiler-options {:devcards           true
                      :output-feature-set :es8}
   :devtools
   {:http-port 3000
    :http-root "out/devcards"}}}}

The devcards-toc is just a regular cljs file in your deps.edn :paths, with an exported init function that calls devcards.core/start-devcard-ui! to start the devcards ui:

(ns devcards-toc
  (:require [devcards.core :as dc]))

(defn ^:export init []
  (dc/start-devcard-ui!))

The server is listening on http://localhost:3000.

See example for a working setup.

Credits

https://github.com/jacekschae/shadow-cljs-devcards