Using Live Reload for faster feedback in Cryogen Web

en
- 14 Nov, 2020
  1. Why?
  2. How it works
  3. Implement Live-Reload
    1. Install LiveReload server component with clj-livereload
  4. Install the browser extension
  5. Known issues

Why?

Some things work better when you have instant feedback. Developing your Cryogen theme is among them. To get (near) instant feedback when developing your theme or writing content you can use Live Reload.

Using this workflow will allow you to work on your theme, save the file and have the browser refresh with your changes.

This flow does not work when you are writing content due to some issues.

This guide is inspired by Cryogen #118.

How it works

To have the browser refresh after you save your files we need a couple of things:

  • a way to monitor the filesystem for changes - Live Reload server component

  • a way to communicate the change to the browser to trigger a reload - Live Reload browser extension

The browser communicates with the server via Web Sockets.

Now, for the live-reload server component we have two options:

  • Add some code into our app to open a live reload port - like clj-livereload

  • Use a stand alone live reload server like Guard live reload

  • Use an IDE plugin/extension that implements the LiveReload server component

I haven’t tried the stand alone approach so I’m going to explain how to use clj-livereload.

Implement Live-Reload

To implement live reload using clj-livereload we need to the following:

  • Add clj-livereload to our cryogen website dependencies in project.clj

  • Add some code in the compilation step to start a live-reload server and monitor

  • Install the Live Reload extension in your browser

This guide assumes you are working on a Cryogen Web website started by following the Quickstart using lein. You will need to adapt it if you are using something else.

Install LiveReload server component with clj-livereload

Firs we need to add the clj-livereload dependency in our project: Open project.clj, find :dependencies key and add [clj-livereload "0.2.0"]. Please use a more recent version if you need to.

You should have something like this:

project.clj
(defproject cryogen "0.1.0"
            ;; REDACTED for brevity
            :dependencies [;; REDACTED for brevity
                           [clj-livereload "0.2.0"]
                           ]
)

Once we have the dependency we need to start the live reload server when we run lein ring server to compile our website.

To do that open src/cryogen/server.clj and start live-reload during ring server initialization like so:

(ns cryogen.server
  (:require
   ;; REDACTED FOR BREVITY
   [clj-livereload.server :as live-reload]
   ))

(defn init []
  (load-plugins)
  (compile-assets-timed)
  (let [ignored-files (-> (resolve-config) :ignored-files)
        ;; We will monitor public-dest dir. Cryogen will output files there.
        public-dest (-> (resolve-config) :public-dest)]
    (start-watcher! "content" ignored-files compile-assets-timed)
    (start-watcher! "themes" ignored-files compile-assets-timed)
    ;; Add these two lines to
    (println (str "Start Live Reload " public-dest))
    (live-reload/start! {:paths [public-dest]
                         :debug? true}))
  )

Once this is done you should test if it works. Run lein ring server and watch the output. You should see something like this at the end of the cryogen compilation:

## REDACTED FOR BREVITY ##
"Elapsed time: 3926.635827 msecs"
Start Live Reload public
Starting LiveReload server
Watching directories...
2020-11-14 23:35:32.238:INFO:oejs.Server:main: jetty-9.2.21.v20170120

Known issues

For some reason this fails sometimes: * The page reloads with a 'Page not found'. Just refresh. This is caused by how cryogen currently works and should be fixed once Support for incremental page compilation is merged.

Tags: documentation cryogen clojure tutorial static website live-reload

Tag cloud

plain text accounting timeclock documentation parser cryogen grammar keepassxc gnome authentication clojure tutorial pass oauth2 password management export hledger oauth2-proxy free software csv website static website kubernetes lexer dex gnome extension babashka k3s contribution time logging FreeIPA Raspberry PI LDAP giving back OpenFaaS Antlr self-hosting serverless cryogen-web contribuție live-reload open source