Search icon CANCEL
Cart icon
Close icon
You have no products in your basket yet
Save more on your purchases!
Savings automatically calculated. No voucher code required
Arrow left icon
All Products
Best Sellers
New Releases
Learning Hub
Free Learning
Arrow right icon
Clojure Web Development Essentials
Clojure Web Development Essentials

Clojure Web Development Essentials: Develop your own web application with the effective use of the Clojure programming language

By Ryan Baldwin
$28.99 $19.99
Book Feb 2015 232 pages 1st Edition
$28.99 $19.99
$15.99 Monthly
$28.99 $19.99
$15.99 Monthly

What do you get with eBook?

Product feature icon Instant access to your Digital eBook purchase
Product feature icon Download this book in EPUB and PDF formats
Product feature icon Access this title in our online reader with advanced features
Product feature icon DRM FREE - Read whenever, wherever and however you want
Buy Now
Table of content icon View table of contents Preview book icon Preview Book

Clojure Web Development Essentials

Chapter 1. Getting Started with Luminus

Ah, getting started! This chapter introduces you to the foundations of Clojure web development using Luminus, a popular web application template for Leiningen. In this chapter, you will:

  • Generate a new web application using the Luminus Leiningen template

  • Get an introduction to the popular libraries, which Luminus uses to handle the various aspects of a web application, and what those libraries do

  • Get an overview of the directory structure generated by Luminus

  • Learn how to fire up the web application on your development machine

In this chapter, we'll create a new web application called hipstr, an application that will help us track our vinyl collection and endow us with obscure credibility. We'll build this application with each subsequent chapter by creating our own route handlers, interacting with a database, authenticating users, validating form input, and reading/writing cookies. By the end of this book, we'll know the Clojure web basics well enough that we'll be wearing plaid shirts and sipping bourbon aged in casks from a place nobody's ever heard of.


Our project will rely heavily on Leiningen, a build and task tool for Clojure. Leiningen allows us to easily maintain our application's dependencies, assists us in common tasks such as database migrations, running tests, producing binaries (jars and wars), and a plethora of other things. Leiningen is akin to Java's build tool Maven (, and Ruby's Rake ( As Leiningen's web page ( concisely puts it: for automating Clojure projects without setting your hair on fire.

If you haven't already installed Leiningen 2.x, head over to and follow the four simple instructions. It will take just 60 seconds, and the world of Clojure will become your oyster.


After you've installed Leiningen, you'll have access to a new command in your terminal, lein. Invoking this command will invoke Leiningen.

Using Leiningen

The basic makeup of a Leiningen task can be summarized as follows:


In the preceding shell pseudo-command, we invoke Leiningen using its binary. The lein $TASK argument is the Leiningen task we want to execute (such as install, jar, etc.), and $TASK_ARGUMENTS is any information required for that task to do its job, including additional subtasks and the arguments for a given subtask. You can see a full list of the available tasks in Leiningen by executing the following command:

# lein --help

You can also view the help content for a specific Leiningen task by executing the following command:

# lein help $TASK

You can use these commands whenever you need to know how to do something in Leiningen.

Generating the application

Leiningen can generate an application skeleton (or scaffolding) from a plethora of different templates. There's a template for nearly everything such as clojurescript projects, web applications (of course), and much more.

To generate a new application, we use the new Leiningen task whose basic syntax is as follows:


The new task expects, at a minimum, a name for the project ($PROJECT_NAME). Optionally, we can provide a specific template to use ($TEMPLATE_NAME). If we don't specify a template, then lein will use the default template, which is a general template for developing libraries.

For our project we'll use the Luminus template, an excellent template for web applications. Luminus generates a project and wires in the libraries to support pretty much every aspect of web development including sessions, cookies, route handling, and template rendering.


At the time of this writing, the Luminus template was at version 1.16.7. To ensure the code examples in this book work, you can force Leiningen to use a specific version of Luminus by modifying Leiningen's profiles.clj file (typically found in your home directory, in a folder called .lein) to include the specific version of Luminus. For example:

:user {:plugins [[luminus/lein-template "1.16.7"]]}

This modification will ensure that version 1.16.7 of the Luminus template is used when generating a Luminus-based application.

Just try the following command:

# lein new luminus hipstr
>> Generating a lovely new luminus project named hipstr…


Downloading the example code

You can download the example code files for all Packt books you have purchased from your account at If you purchased this book elsewhere, you can visit and register to have the files e-mailed directly to you.

The preceding command will generate a fully runnable application in a directory called hipstr. You can run the application by using cd hipstr to enter into the hipstr directory and then execute the following command:

# lein ring server
>>(Retrieving im/chit/cronj/1.0.1/cronj-1.0.1.pom from clojars)
>>…a whole bunch of Retrieving…
>>…and other output…
>>Started server on port 3000

In the preceding command line, the lein ring server command updates our class path with the dependencies required to compile and run the app. It then launches the development server (an embedded Jetty server) and starts serving on port 3000. Lastly, it launches our default web browser and navigates to the root page.


In the preceding example, ring is the Leiningen task, and server is the ring subtask. You can view a full list of ring subtasks by entering the lein help ring command in your terminal.

The subsequent output of lein ring server is a series of debug statements that lets us know what the heck is going on during the startup process. Any generated exceptions or problems that occur while attempting to launch the application will be emitted as part of this output.

Getting help

If anything doesn't go as planned, or you're stumped and confused, feel free to check the Luminus documentation at You can also get some help from people in the Luminus community (!forum/luminusweb) or the Ring community (!forum/ring-clojure). Of course, there's always the Clojure group on Google Groups (

Dependencies of the app

The Luminus template provides good starting defaults for a typical web application by using popular libraries. It also configures common tasks (such as logging) and provides a few default route handlers (URL handlers).

Taking a peek at the generated project.clj file, we see all the dependencies included by the luminus template. At the time of writing, the project.clj file produced the following dependencies:

  :dependencies [[org.clojure/clojure "1.6.0"]
                [lib-noir "0.9.4"]
                [ring-server "0.3.1"]
                [selmer "0.7.2"]
                [com.taoensso/timbre "3.3.1"]
                [com.taoensso/tower "3.0.2"]
                [markdown-clj "0.9.55"
                  :exclusions [com.keminglabs/cljx]]
                [environ "1.0.0"]
                [im.chit/cronj "1.4.2"]
                [noir-exception "0.2.2"]
                [prone "0.6.0"]]


Luminus is a popular and active project, and is constantly getting better. Between now and the time this book goes to press and you purchasing one for each of your friends and yourself, it's possible that the template will have changed. At the time of writing, version 1.16.7 of the luminus template was used. If you used a more recent version your results may vary.

The first dependency should look familiar (if not, then this book isn't for you… yet). The rest, however, might appear to be a mystery. I'll spare you the effort of searching it online and break it down for you.

  • lib-noir: This contains a slough of useful utilities to create web applications using the Ring framework, such as routing, redirections, static resources, password hashing, file uploads, sessions and cookies, and so on. It's the work horse for much of the plumbing common to all web applications. Visit the following website:

  • ring-server: This is a bit of an omnibus library, encompassing several other Ring-related libraries. Ring is a web application library, which acts as an abstraction between our web application (hipstr) and the underlying web server or servlet container. You can think of it as something akin to Java's Servlet API (which Ring fulfills), Python's WSGI, or Ruby's Rack. Ring Server, by contrast, is a library that starts a web server capable of serving a Ring handler. We'll get into more detail in Chapter 2, Ring and the Ring Server. To get more information about Ring Server, visit:

  • selmer: This is an HTML template rendering a library modeled after the ubiquitous Django framework. Selmer allows us to generate dynamic pages, script loops and conditional rendering, extend other Selmer templates, and so on. We'll talk more about Selmer in Chapter 4, URL Routing and Template Rendering. To get more information on selmer, visit:

  • timbre: Timbre is a pure Clojure logging library. It's pretty much like every other logging library on the planet, complete with somewhat confusing configuration. We'll cover Logging in Chapter 3, Logging. You can also visit, to get more information on Timbre.

  • tower: This is similar to its sibling timbre, and is a pure Clojure library that provides support for internationalization and localization. You can refer to

  • markdown-clj: This is a simple library that allows us to compile markdown to html. For more information, you can visit

  • environ: This allows us to create different application configurations for different environments (think development versus production). We'll work with environ in Chapter 11, Environment Configuration and Deployment.

  • cronj: This is a simple, straightforward library for creating cron-like scheduled tasks. To know more about cronj, visit

  • noir-exception: This provides prettified, rendered, exception stacks in the browser as well as to log files. The noir-exception library highlights your application's namespaces in their own color, easily separating your called code from the rest of the first and third party Clojure libs.

  • prone: This produces the most amazing exception reporting output you might have ever seen. (

Luminus file structure

The luminus template generates web applications using a fairly typical directory structure. However, it also produces a number of Clojure namespaces that can cause a bit of confusion if you're brand new to Clojure web development. You can either open the project using your favorite Clojure editor, or do the following from the terminal:

# find . -print | sed -e 's;[^/]*/;|____;g;s;____|; |;g'


The preceding command line is a nasty thing to eyeball and type. You can copy and paste the preceding command from

In either case, you should see output similar to the following:

Luminus generates three directories at the root of the application directory: resources, src, and test.

The resources directory contains the files that will compose the front end of our applications. The public folder contains resources publicly available to the client, such as our JavaScript, CSS, and images. By contrast, the templates directory contains our Selmer templates used for the heavy rendering of HTML parts. All of these files will be made available on our class path; however, only those in the public folder will be actually available to the client.

The src directory contains all of the necessary namespaces for running our application, and the test directory contains all the necessary namespaces for testing our src.

In addition to the directories, however, Luminus also generated some files in the src directory. These files are the bare minimum requirement to successfully run our application, and each one handles specific functionality. Let's take a brief look at the base functionality contained in each file.


The hipstr.util namespace is a simple namespace where you can put various helper functions you find yourself frequently using during the development of your application. Out of the box, Luminus generates a hipstr.util namespace with a single function, md->html, which converts markdown into HTML. Typically, I try to avoid namespaces such as util.clj because they eventually turn into the junk drawer in your kitchen, but they can be useful on smaller projects if things don't get too crowded. The following block of code shows the hipstr.util namespace:

(ns hipstr.util
  (:require [ :as io]
            [markdown.core :as md]))

(defn md->html
  "reads a markdown file from public/md and returns an HTML
  (md/md-to-html-string (io/slurp-resource filename)))


One of lib-noir's exposed functionalities is session management (which we'll discuss in detail in Chapter 10, Sessions and Cookies). The default session pool in Luminus is an in-memory session pool, a shortcoming of which is that expired sessions are only removed from memory when the server handles a request associated with an expired session. As a result, old stale sessions can linger in memory indefinitely, straining memory resources on the server. Luminus boilerplates a cronj job in the hipstr.sessions-manager namespace, which occasionally removes stale, unused sessions. By default, the job runs every 30 minutes. Take a look at the following lines of code:

(ns hipstr.session-manager
  (:require [noir.session :refer [clear-expired-sessions]]
            [cronj.core :refer [cronj]]))

(def cleanup-job
    [{:id "session-cleanup"
      :handler (fn [_ _] (clear-expired-sessions))
      :schedule "* /30 * * * * *"
      :opts {}}]))


The hipstr.layout namespace houses the functions that are used to render the HTTP response body. By default, Luminus creates a single function, render, which will render any Selmer template onto the HTTP response.The following lines of code is for the hipstr.layout namespace:

(ns hipstr.layout
  (:require [selmer.parser :as parser]
            [clojure.string :as s]
            [ring.util.response :refer [content-type response]]
            [compojure.response :refer [Renderable]]
            [environ.core :refer [env]]))

(def template-path "templates/")

(deftype RenderableTemplate [template params]
  (render [this request]
      (->> (assoc params
        (s/replace template #".html" "-selected"))"active"
          :dev (env :dev)
              (if-let [context (:servlet-context request)]
              ;; If we're not inside a serlvet environment
              ;; (for example when using mock requests), then
              ;; .getContextPath might not exist
              (try (.getContextPath context)
                (catch IllegalArgumentException _ 
            (parser/render-file (str template-path template))
          "text/html; charset=utf-8")))

(defn render [template & [params]]
(RenderableTemplate. template params))

The key to the hipstr.layout namespace is that it remains high level and generic. You should avoid writing functions with domain knowledge in this namespace, and instead focus on generating response bodies. If you put an explicit URL or filename in this namespace, you're probably doing it wrong.


Middleware, for the unfamiliar, is a function that can work with an incoming request prior to the request being handled by the main application (that is our proverbial business logic). Its function is similar to how a car moves through an assembly line; each employee working the line is responsible for interacting with the car in some specific way. Much like how at the end of the assembly line the car is in its final state and ready for consumption, so is the request in its final state and ready for processing by the main application. The following code is for the hipstr.middleware namespace:

(ns hipstr.middleware
  (:require [taoensso.timbre :as timbre]
            [selmer.parser :as parser]
            [environ.core :refer [env]]
            [selmer.middleware :refer [wrap-error-page]]
            [prone.middleware :refer [wrap-exceptions]]
            [noir-exception.core :refer [wrap-internal-error]]))

(defn log-request [handler]
  (fn [req]
    (timbre/debug req)
    (handler req)))

(def development-middleware

(def production-middleware
  [#(wrap-internal-error % :log (fn [e] (timbre/error e)))])

(defn load-middleware []
  (concat (when (env :dev) development-middleware)

The hipstr.middleware namespace has two primary responsibilities. The first is that it ties together all the different middleware we want across any of our runtime environments. The second is that it gives us a place to add additional middleware, if desired. Of course, there's nothing prohibiting us from writing our middleware in a new namespace, but for the sake of simplicity and for this book, we'll simply create additional middleware in the hipstr.middleware namespace.


One of the directories that Luminus generated was a route folder. Routes are what tie a request to a specific handler (or, in layman's terms, a chunk of code to be executed based on the URL the request is sent to). Luminus generates 2 routes for us:

  • A / route, which renders the result of calling the home-page function, which ultimately renders the home page you see at startup

  • A /about route, which renders the result of the about-page function, responsible for rendering the about.html page

Take a look at the following lines of code:

(ns hipstr.routes.home
  (:require [compojure.core :refer :all]
            [hipstr.layout :as layout]
            [hipstr.util :as util]))

(defn home-page []
    "home.html" {:content (util/md->html "/md/")}))

(defn about-page []
  (layout/render "about.html"))

(defroutes home-routes
  (GET "/" [] (home-page))
  (GET "/about" [] (about-page)))

We will create a couple of our own routing namespaces over the course of this book. The routes we'll create in those namespaces will follow the same pattern demonstrated in the preceding hipster.routes.home namespace. We'll talk a bit more about routes in Chapter 4, URL Routing and Template Rendering.


Everything we've seen in this chapter is brought together into a single, harmonious, running application in the hipstr.handler namespace, explained in the following lines of code. Opening the file for a cursory scan reveals our cron job to clean up expired sessions, the home-routes from the hipstr.routes.home namespace, the configuration of our Timbre logging, and so on.

(ns hipstr.handler
  (:require [compojure.core :refer [defroutes]]
    ; ... snipped for brevity …
    [cronj.core :as cronj]))

(defroutes base-routes
  (route/resources "/")
  (route/not-found "Not Found"))

(defn init
  "init will be called once when
    app is deployed as a servlet on
    an app server such as Tomcat
    put any initialization code here"
  ;… snipped for brevity …)

(defn destroy
  "destroy will be called when your application
   shuts down, put any clean up code here"
  ; ... snipped for brevity ...)

;; timeout sessions after 30 minutes
(def session-defaults
  {:timeout (* 60 30)
   :timeout-response (redirect "/")})

(defn- mk-defaults
       "set to true to enable XSS protection"
       ;... snipped for brevity ...

(def app (app-handler
            ;; add your application routes here
            [home-routes base-routes]
            ;; add custom middleware here
            :middleware (load-middleware)
            :ring-defaults (mk-defaults false)
            ;; add access rules here
            :access-rules []
            ;; serialize/deserialize the following data formats
            ;; available formats:
            ;; :json :json-kw :yaml :yaml-kw :edn :yaml-in-html
            :formats [:json-kw :edn :transit-json]))

We'll get into detail about what all is happening, and when, in Chapter 2, Ring and the Ring Server.


The last Luminus generated namespace, hipstr.repl, is one that often confuses beginners because it's strikingly similar to hipster.handler. The hipstr.repl namespace has a start-server and stop-server function, much like hipster.handler. However, hipstr.repl allows us to start and stop our development server from the Clojure REPL. This might seem like a weird thing to do, but by running our server from the REPL we can modify our running system and the changes will be "automagically" reloaded in our server. No need for the time consuming and frustrating "compile-deploy-restart-grab-a-coffee-and-twiddle-your-thumbs cycle!"

(ns hipstr.repl
  (:use hipstr.handler
        [ring.middleware file-info file]))

(defonce server (atom nil))

(defn get-handler []
  ;; #'app expands to (var app) so that when we reload our code,
  ;; the server is forced to re-resolve the symbol in the var
  ;; rather than having its own copy. When the root binding
  ;; changes, the server picks it up without having to restart.
  ; ... snipped for brevity ...

(defn start-server
  "used for starting the server in development mode from REPL"
  [& [port]]
  ; ... snipped for brevity ...

(defn stop-server []
  ;… snipped for brevity …

Incorporating the REPL into your development workflow is a wonderful thing to do. You can load your namespace into the REPL while you work on it and test the code while you're developing right then and there. In fact, some IDEs such as LightTable take this a step further, and will "live-evaluate" your code as you type. The ability of running the dev server from the REPL completes the circle.


If you're not currently using a decent IDE for Clojure development, I strongly encourage you to give LightTable a try. It's free, open source, lightweight, and very different than anything you're used to. It's quite good. Check it out at


In this chapter, you learned how to generate a new Clojure-based web application using Leiningen and the Luminus template. We also got a high-level understanding of each dependency, and how Luminus structures its projects. In the next chapter we'll take a detailed look at the Ring and Ring Server libraries, and what they're responsible for. It sounds a little dry, I know, but I recommend that you read it. There will be cake and punch at the end, but without all the calories of cake and punch.

Left arrow icon Right arrow icon

Key benefits

What you will learn

Generate a fully runnable web application using the Luminus Leiningen application template Explore the basics of the underlying Ring framework and the Ring Server Configure URL Routing, Logging, and some testing basics Create new web pages using the Selmer template rendering library Validate usersubmitted form data Store and retrieve data to and from a database Configure, package, and deploy the finished application

Product Details

Country selected

Publication date : Feb 24, 2015
Length 232 pages
Edition : 1st Edition
Language : English
ISBN-13 : 9781784392222
Category :

What do you get with eBook?

Product feature icon Instant access to your Digital eBook purchase
Product feature icon Download this book in EPUB and PDF formats
Product feature icon Access this title in our online reader with advanced features
Product feature icon DRM FREE - Read whenever, wherever and however you want
Buy Now

Product Details

Publication date : Feb 24, 2015
Length 232 pages
Edition : 1st Edition
Language : English
ISBN-13 : 9781784392222
Category :

Table of Contents

19 Chapters
Clojure Web Development Essentials Chevron down icon Chevron up icon
Credits Chevron down icon Chevron up icon
About the Author Chevron down icon Chevron up icon
About the Reviewers Chevron down icon Chevron up icon Chevron down icon Chevron up icon
Preface Chevron down icon Chevron up icon
1. Getting Started with Luminus Chevron down icon Chevron up icon
2. Ring and the Ring Server Chevron down icon Chevron up icon
3. Logging Chevron down icon Chevron up icon
4. URL Routing and Template Rendering Chevron down icon Chevron up icon
5. Handling Form Input Chevron down icon Chevron up icon
6. Testing in Clojure Chevron down icon Chevron up icon
7. Getting Started with the Database Chevron down icon Chevron up icon
8. Reading Data from the Database Chevron down icon Chevron up icon
9. Database Transactions Chevron down icon Chevron up icon
10. Sessions and Cookies Chevron down icon Chevron up icon
11. Environment Configuration and Deployment Chevron down icon Chevron up icon
Using Korma – a Clojure DSL for SQL Chevron down icon Chevron up icon
Index Chevron down icon Chevron up icon

Customer reviews

Top Reviews
Rating distribution
Empty star icon Empty star icon Empty star icon Empty star icon Empty star icon 0
(0 Ratings)
5 star 0%
4 star 0%
3 star 0%
2 star 0%
1 star 0%
Top Reviews
No reviews found
Get free access to Packt library with over 7500+ books and video courses for 7 days!
Start Free Trial


How do I buy and download an eBook? Chevron down icon Chevron up icon

Where there is an eBook version of a title available, you can buy it from the book details for that title. Add either the standalone eBook or the eBook and print book bundle to your shopping cart. Your eBook will show in your cart as a product on its own. After completing checkout and payment in the normal way, you will receive your receipt on the screen containing a link to a personalised PDF download file. This link will remain active for 30 days. You can download backup copies of the file by logging in to your account at any time.

If you already have Adobe reader installed, then clicking on the link will download and open the PDF file directly. If you don't, then save the PDF file on your machine and download the Reader to view it.

Please Note: Packt eBooks are non-returnable and non-refundable.

Packt eBook and Licensing When you buy an eBook from Packt Publishing, completing your purchase means you accept the terms of our licence agreement. Please read the full text of the agreement. In it we have tried to balance the need for the ebook to be usable for you the reader with our needs to protect the rights of us as Publishers and of our authors. In summary, the agreement says:

  • You may make copies of your eBook for your own use onto any machine
  • You may not pass copies of the eBook on to anyone else
How can I make a purchase on your website? Chevron down icon Chevron up icon

If you want to purchase a video course, eBook or Bundle (Print+eBook) please follow below steps:

  1. Register on our website using your email address and the password.
  2. Search for the title by name or ISBN using the search option.
  3. Select the title you want to purchase.
  4. Choose the format you wish to purchase the title in; if you order the Print Book, you get a free eBook copy of the same title. 
  5. Proceed with the checkout process (payment to be made using Credit Card, Debit Cart, or PayPal)
Where can I access support around an eBook? Chevron down icon Chevron up icon
  • If you experience a problem with using or installing Adobe Reader, the contact Adobe directly.
  • To view the errata for the book, see and view the pages for the title you have.
  • To view your account details or to download a new copy of the book go to
  • To contact us directly if a problem is not resolved, use
What eBook formats do Packt support? Chevron down icon Chevron up icon

Our eBooks are currently available in a variety of formats such as PDF and ePubs. In the future, this may well change with trends and development in technology, but please note that our PDFs are not Adobe eBook Reader format, which has greater restrictions on security.

You will need to use Adobe Reader v9 or later in order to read Packt's PDF eBooks.

What are the benefits of eBooks? Chevron down icon Chevron up icon
  • You can get the information you need immediately
  • You can easily take them with you on a laptop
  • You can download them an unlimited number of times
  • You can print them out
  • They are copy-paste enabled
  • They are searchable
  • There is no password protection
  • They are lower price than print
  • They save resources and space
What is an eBook? Chevron down icon Chevron up icon

Packt eBooks are a complete electronic version of the print edition, available in PDF and ePub formats. Every piece of content down to the page numbering is the same. Because we save the costs of printing and shipping the book to you, we are able to offer eBooks at a lower cost than print editions.

When you have purchased an eBook, simply login to your account and click on the link in Your Download Area. We recommend you saving the file to your hard drive before opening it.

For optimal viewing of our eBooks, we recommend you download and install the free Adobe Reader version 9.