search

bhauman / devcards

Devcards aims to provide a visual REPL experience for ClojureScript
1.53k stars 115 forks source link

readme

Devcards

Current release:

Clojars Project

Devcards aims to provide ClojureScript developers with an interactive visual REPL. Devcards makes it simple to interactively surface code examples that have a visual aspect into a browser interface.

Devcards is not a REPL, as it is driven by code that exists in your source files, but it attempts to provide a REPL-like experience by allowing developers to quickly try different code examples and see how they behave in an actual DOM.

Devcards is centered around a notion of a card. Every card represents some code to be displayed. Devcards provides an interface which allows the developer to navigate to different namespaces and view the cards that have been defined in that namespace.

When used in conjunction with lein figwheel the cards can be created and edited "live" in one's ClojureScript source files. Essentially lifting the code example out of the file into the browser for you to try out immediately.

For example, the following code will create a card for a Sablono template that you might be working on:

(defcard two-zero-48-view 
  (sab/html
    [:div.board 
      [:div.cells
        [:div {:class "cell xpos-1 ypos-1"} 4]
        [:div {:class "cell xpos-1 ypos-2"} 2]
        [:div {:class "cell xpos-1 ypos-3"} 8]]]))

When used with lein-figwheel, saving the file that contains this definition will cause this Sablono template to be rendered into the Devcards interface.

Read: The Hard Sell

See the introduction video.

See the Strange Loop talk.

Why???

We primarily design and iterate on our front end applications inside the main application itself. In other words, our execution environment is constrained by the shape and demands of the application we are working on. This is extremely limiting.

This doesn't seem like a problem, eh?

Well think of it this way: the main application and its many subcomponents can potentially embody a tremendous number of states. But working against a single instance of the application only lets you look at one state at a time. What if you could work on the application or component in several states at the same time? This is a powerful multiplier. You are increasing the bandwidth of the feedback you are getting while working on your code.

Another problem is that we often manually place our components into different important states to run them through their paces as we develop them. But ... these test states are ephemeral. Wouldn't it be better to keep a development "page" as a permanent asset where these components are displayed in these various states as a

Developing your components in a different context than your main application starkly reveals environmental coupling, in the same way that unit tests often do. This can lead to developing components that are more independent than the ones that are developed inside the main app.

One more thing: developing your components in a SPA that isn't your main application provides you a space to create and use visual components that are intended to help you understand the code you are working on. We are UI programmers after all, why wait for IDEs to create the tools we need? Most problems are unique and can benefit tremendously from the creation of a very thin layer of custom tooling.

Developing inside the main application is constraining and it isn't until you develop inside a meta application that you can see this more clearly. With a meta application, you now have a space to try things out that do not have to interface or fit into the main application. This is extremely important as it gives you space to try new things without the cost that is currently associated with experiments (branching, new html host file, etc).

Examples

Regardless of which path you take to get started with Devcards please see the following examples:

Introduction examples (src)

An example implementation of 2048 (src)

An introduction to the defcard api (src)

Super Quick Start

There is a Devcards Leiningen template to get you up an running quickly.

Make sure you have the latest version of leiningen installed.

Type the following to create a fresh project with devcards setup for you:

lein new devcards hello-world

Then

cd hello-world

lein figwheel

to start the figwheel interactive devserver.

Then visit http://localhost:3449/cards.html

Quick Trial

If you want to quickly interact with a bunch of devcards demos:

git clone https://github.com/bhauman/devcards.git

cd devcards

lein figwheel

Then visit http://localhost:3449/devcards/index.html

The code for the cards you are viewing in the devcards interface is located in the example_src directory.

Go ahead and edit the code in the examples and see how the devcards interface responds.

Usage

First make sure you include the following :dependencies in your project.clj file.

[org.clojure/clojurescript "1.10.238"]
[devcards "0.2.5"]

You will need an HTML file to host the devcards interface. It makes sense to have a separate file to host devcards. I would create the following resources/public/cards.html file (this is the same file as in the leiningen template).

<!DOCTYPE html>
<html>
  <head>
    <meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no">
    <meta charset="UTF-8">
    <link href="https://github.com/bhauman/devcards/blob/master/css/example.css" rel="stylesheet" type="text/css">
  </head>
  <body>
    <script src="https://github.com/bhauman/devcards/raw/master/js/compiled/example.js" type="text/javascript"></script>
  </body>
</html>

Usage With Figwheel

lein-figwheel is not required to use Devcards but it is definitely recommended if you want to experience interactive coding with Devcards. See the lein-figwheel repo for instructions on how to do that.

Configure your devcards build:

:cljsbuild {
 :builds [
   {:id "devcards"
    :source-paths ["src"]   
    :figwheel { :devcards true } ;; <- note this
    :compiler { :main    "{{your lib name}}.core"
                :asset-path "js/compiled/devcards_out"
                :output-to  "resources/public/js/{{your lib name}}_devcards.js"
                :output-dir "resources/public/js/devcards_out"
                :source-map-timestamp true }}]
}

Next you will need to include the Devcards macros into your file:

(ns example.core
  (:require
   [sablono.core :as sab]) ; just for example
  (:require-macros
   [devcards.core :refer [defcard]]))

(defcard my-first-card
  (sab/html [:h1 "Devcards is freaking awesome!"]))

This will create a card in the devcards interface.

Take a look at the defcard api (src)

Usage without Figwheel

Figwheel does some magic so that Devcards can be included or excluded from your code easily. You can certainly use Devcards without Figwheel, but there are three things that you will need to do.

You need to specify :devcards true in the build-options of your ClojureScript build

{ :main    "{{name}}.core"
  :devcards true ; <- note this
  :asset-path "js/compiled/devcards_out"
  :output-to  "resources/public/js/{{sanitized}}_devcards.js"
  :output-dir "resources/public/js/devcards_out"
  :source-map-timestamp true }

This is important as it is a signal to the defcard macro to render the cards. This is equivalent to adding :figwheel { :devcards true } in our figwheel based build above, but since we aren't using figwheel in this build adding the figwheel options doesn't help.

You will need to require devcards.core in the files that use devcards as such:

(ns example.core
  (:require
   [devcards.core :as dc] ; <-- here
   [sablono.core :as sab]) ; just for this example
  (:require-macros
   [devcards.core :refer [defcard]])) ; <-- and here

(defcard my-first-card
  (sab/html [:h1 "Devcards is freaking awesome!"]))

This isn't required with Figwheel because it puts devcards.core into the build automatically.

You will need to start the Devcards UI

(devcards.core/start-devcard-ui!)

Make sure this is included in the file you have specified as :main in your build options. As mentioned above, you don't want the Devcards UI to compete with your application's UI so you will want to make sure it isn't getting launched.

Devcards as a Standalone Website

Devcards can easily be hosted as a standalone website by following steps similar to those needed to use it locally without figwheel. In this example, we will be adding a hostedcards profile to build our site.

Add :devcards true to the build-options of our ClojureScript build profile

{:id "hostedcards"
 :source-paths ["src"]
 :compiler {:main "{{your lib name}}.core"
            :devcards true ; <- note this
            :asset-path "js/compiled/out"
            :output-to  "resources/public/js/compiled/{{your lib name}}.js"
            :optimizations :advanced}}

Require devcards.corein the files that use devcards

(ns {{your lib name}}.core
  (:require
   [devcards.core :as dc]) 
  (:require-macros
   [devcards.core :refer [defcard]]))

Start the Devcards UI in {{your lib name}}.core

(devcards.core/start-devcard-ui!)

Include the compiled JS in our HTML

<!DOCTYPE html>
<html>
  <head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <link href="https://github.com/bhauman/devcards/blob/master/css/{{your lib name}}.css" rel="stylesheet" type="text/css">
  </head>
  <body>
    <div id="main-app-area"></div>
    <script src="https://github.com/bhauman/devcards/raw/master/js/compiled/{{your lib name}}.js" type="text/javascript"></script>
  </body>
</html>

Run our Build

lein cljsbuild once hostedcards

Once the build is complete, simply copy the contents of resources\public to your webserver and serve it up as you would any other page.

FAQ

Does Devcards only work with React or Om?

Nope, it can work with arbitrary CLJS code examples as well. Devcards provides a dom-node helper that will give you a node in the DOM to display stuff in.

Does Devcards require Figwheel?

Devcards will work automatically with REPL workflow or boot-reload.

You can also just reload the browser after making a change.

What do I do for deployment?

Devcards has been rewritten so that you can write Devcards alongside your code with no impact on your production code.

That being said it is often helpful to move the bulk of your cards to a different buildpath that is only built when working on the devcards build.

When working with devcards I often have three builds "devcards", "dev", "prod".