DEV Community

shaolang
shaolang

Posted on • Updated on • Originally published at shaolang.github.io

Storybook.JS with Shadow-CLJS

#clojurescript #storybook #react

Storybook.JS is a very interesting development tool from JavaScript ecosystem1. This tutorial shows how we can use it with Shadow-CLJS. The code resides at storybook.js-with-shadow-cljs repo.

Prerequisites

The tutorial uses the following:

Make sure the first two are installed prior the tutorial. The others will be installed along the way.

Getting a simple React app running

Let's create the scaffold to kick-start:

$ mkdir acme
$ cd acme
$ npm init        # just keep pressing enter until the prompt ends
$ npm install --save-dev shadow-cljs
Enter fullscreen mode Exit fullscreen mode

In the generated package.json, add a helper script to launch shadow-cljs and automatically compile when it detect changes:

"scripts": {
  "dev": "shadow-cljs watch frontend"
}
Enter fullscreen mode Exit fullscreen mode

The script uses the :frontend profile defined in shadow-clj.edn for ClojureScript compiler. Run npx shadow-cljs init to generate the skeleton shadow-cljs.edn file and edit it as follows:

;; shadow-cljs configuration
{:source-paths
  ["src/dev"
   "src/main"
   "src/test"]

 :dependencies
 [[reagent "1.0.0"]]

 :builds
 {:frontend {:target  :browser
             :modules {:main {:init-fn acme.core/init}}}}}
Enter fullscreen mode Exit fullscreen mode

Line 8 adds Reagent as a dependency; lines 11 and 12 create the profile :frontend (that matches the npm script's shadow-cljs watch command). This profile specifies that the build targets the browser and should generate the file main.js ('cos of the :main key) that will invoke acme.core/init function at initialization. Let's implement init that uses a simple Reagent component in src/main/acme/core.cljs:

(ns acme.core
  (:require [reagent.dom :refer [render]]))

(defn header [text]
  [:h1 text])

(defn init []
  (render [header "Hello, World!"]
          (js/document.getElementById "app")))
Enter fullscreen mode Exit fullscreen mode

Simple enough: a custom header component that outputs the given text in an h1 element and the init function that renders the header. To see this glorious app render, create the public/index.html as follows:

<!doctype html>
<html>
  <head>
    <meta charset='utf-8'>
    <title>Acme</title>
  </head>
  <body>
    <div id='app'></div>
    <script src='js/main.js'></script>
  </body>
</html>
Enter fullscreen mode Exit fullscreen mode

By default, Shadow-CLJS generates the output to public/js, hence the highlighted line (line 9). When the page is ready, init will run and renders the header component. Before running npm run dev, add dev-http to shadow-cljs.edn to configure the dev-server to listen to port 8080 and serve artifacts from public directory:

;; shadow-cljs configuration
{:source-paths
  ["src/dev"
   "src/main"
   "src/test"]

 :dev-http {8080 "public"}

 :dependencies
 [[reagent "1.0.0"]]

 :builds
 {:frontend {:target  :browser
             :modules {:main {:init-fn acme.core/init}}}}}
Enter fullscreen mode Exit fullscreen mode

With all these set up, run npm run dev and load the page localhost:8080 in your favorite browser; you should see "Hello, World!":

screenshot of "Hello, World!" rendered in browser

Some cleanup

Before integrating with Storybook.JS, let's do some cleaning up: extract the custom header component to its own namespace and make acme.core/init use that extracted one instead. First, the extracted component at src/main/acme/components/header.cljs:

(ns acme.components.header)

(defn header [text]
  [:h1 text])
Enter fullscreen mode Exit fullscreen mode

Then, in src/main/acme/core.cljs, delete header function and require the header component namespace (as shown in line 2 below):

(ns acme.core
  (:require [acme.components.header :refer [header]]
            [reagent.dom :refer [render]]))

(defn init []
  (render [header "Hello, World!"]
          (js/document.getElementById "app")))
Enter fullscreen mode Exit fullscreen mode

Adding Storybook.JS to the mix

Time to add Storybook.JS to the project. Install it with npm install --save-dev @storybook/react; then create .storybook/main.js with the following contents to configure Storybook.JS to look for stories in public/js/stories directory:

module.exports = {
  stories: ['../public/js/stories/**/*_stories.js'],
};
Enter fullscreen mode Exit fullscreen mode

Update shadow-cljs.edn to create a new profile specifically for stories that outputs the transpiled stories to public/js/stories too:

;; shadow-cljs configuration
{:source-paths
  ["src/dev"
   "src/main"
   "src/stories"
   "src/test"]

 :dev-http {8080 "public"}

 :dependencies
 [[reagent "1.0.0"]]

 :builds
 {:frontend {:target  :browser
             :modules {:main {:init-fn acme.core/init}}}
  :stories  {:target      :npm-module
             :entries     [acme.stories.header-stories]
             :output-dir  "public/js/stories"}}}
Enter fullscreen mode Exit fullscreen mode

A few notable points on the new :stories profile:

  • :entries specifies the namespaces to transpile to stories; unlike :frontend profile that specifies the target filename to output to (main.js), Shadow-CLJS uses the namespace as the output filename, e.g., acme.stories.header_stories.js
  • :target states the build should target npm module which works for Storybook.JS2

Add two script commands to package.json to ease the auto-compilation of stories and to start Storybook.JS:

"scripts": {
  "dev": "shadow-cljs watch frontend",
  "dev-stories": "shadow-cljs watch stories",
  "storybook": "start-storybook"
}
Enter fullscreen mode Exit fullscreen mode

And finally, the story. Let' create a very simple story at src\stories\acme\stories\header_stories.cljs that says "Hello, World!":

(ns acme.stories.header-stories
  (:require [acme.components.header :refer [header]]
            [reagent.core :as r]))

(def ^:export default
  #js {:title     "Header Component"
       :compoent  (r/reactify-component header)})

(defn ^:export HelloWorldHeader []
  (r/as-element [header "Hello, World!"]))
Enter fullscreen mode Exit fullscreen mode

The snippet above uses Component Story Format, hence the need to add the metadata ^:export to default and HelloWorldHeader. Because Storybook.JS operates on React components, reactify-component at line 7 turns the Reagent component into a React one.3 With all these preparation, run npm run dev-stories in one console, and npm run storybook in another. You should see Storybook.JS render our first story:

Rendering of Header component in Storybook

For the fun of it, let' append another story to header-stories:

(defn ^:export GoodbyeSekaiHeader []
  (r/as-element [header "Goodbye, Sekai!"]))
Enter fullscreen mode Exit fullscreen mode

Another rendering of Header component in Storybook

Wrapping up

That concludes this tutorial on using Storybook.JS with Shadow-CLJS. In this case, we are using Reagent to create the components for Storybook.JS to render. It shouldn't be that difficult to adapt the setup to work with other ClojureScript rendering libraries, e.g., Helix.

  1. ClojureScript world also has a similar devcards. ↩

  2. Shadow-CLJS has a new :esm target that outputs to ES Modules, but as of this writing, it is cumbersome to use (the ^:export metadata hint isn't working, thus requiring the need to declare all exports in shadow-cljs.edn. ↩

  3. Refer to Reagent's tutorial on Interop with React for more information. ↩

Top comments (0)

Read next

thatanjan profile image

10 things about component composition in nextjs

Anjan Shomodder -

prolificnicole profile image

Can Bootstrap be added to React?

Prolific12 -

srwaditya profile image

Understanding Lifecycle Events in React and Performance Optimization

Aditya Shrivastava -

sariah profile image

Top 10 Tools Every React Developer Needs in 2024

Sariah -