Between Two Parens

Deploy ClojureScript to Github Pages

posted on and last updated

This blog will guide you through the process of building and deploying a minimal static website to Github Pages. By the end we should see how straightforward and accessible working with ClojureScript has become. Before we dive in, let's introduce the key players.

What is ClojureScript?

ClojureScript, like Elm or Reason, is a compile to js programming language. It's different from JavaScript because its data structures are immutable, its paradigm is functional and it's part of a family of programming languages called lisp. The tangible benefits are that you can experience a world of web dev where classes of problems influenced by state and questionable language design are significantly reduced. If nothing else, ClojureScript is guarenteed to make you think different.

Github Pages and Static Sites?

Github Pages is a service provided by Github which allows you to freely host your static website. For the uninitiated, a static website is when you write your website in plain old html, css and javascript ClojureScript. You don't need servers, databases or additonal server side code. The benefits include increased performance, a quick development workflow and enhanced website security. The downsides are that static websites will not be able to acheive all the cool features of a beefy web app.

With this in mind, let's start coding.

Let's start by getting Clojure setup on your local machine. To do this, visit the ClojureScript Quickstart and follow the instructions there.

Not sure if you have everything setup properly? We can run a quick sanity check in your terminal by executing the following command:

clj -Stree

You should see a response like this:

org.clojure/clojure 1.10.3
org.clojure/spec.alpha 0.2.194
org.clojure/core.specs.alpha 0.2.56

Setting up your HTML

For those that went through the Github Pages quickstart, you should have a repo with a sad little index.html inside of it. Open your index.html and add some life to it by making it look like this:

<!DOCTYPE html>
<html>
  <head>
    <title>Github Pages + ClojureScript</title>
    <link rel="stylesheet" type="text/css" href="style.css" />
  </head>
  <body>
    <h1 class="site__title">
      <span class="site__title-text">Hello ClojureScript</span>
    </h1>
    <script src="/demo-clojurescript-gh-pages/out/main.js"></script>
  </body>
</html>

Setting up your CSS

The next thing we want to do is add a style.css file at the same level as our index.html file so we can make our hello world look gorg'

:root {
  --color-purple: rgba(197, 18, 193, 1);
  --color-pink: rgba(241, 50, 50, 1);
}

body {
  margin: 0;
  height: 100vh;
  display: flex;
  font-family: Arial;
  align-items: center;
  justify-content: center;
}

.site__title {
  font-size: 100px;
  width: 50%;
  text-align: center;
}

.site__title-text {
  background: -webkit-linear-gradient(
    34deg,
    var(--color-purple),
    var(--color-pink)
  );
  -webkit-background-clip: text;
  -webkit-text-fill-color: transparent;
}

Now that we have our HTML and CSS, we need to add ClojureScript.

Setting up your ClojureScript

To do anything with ClojureScript, we need to configure our project to use it. This begins by adding ClojureScript as a dependency. The way we do this in Clojure land is by creating a file called deps.edn at the same level as our index.html. Once you have created your deps.edn, open it and add the following code:

{:deps {org.clojure/clojurescript {:mvn/version "1.10.866" }}}

Let's recap a bit. At this point, your directory structure should look like this:

.
├── deps.edn
├── style.css
└── index.html

If yes, we are good to move onto the next step: writing ClojureScript!

Like most code projects our code is going to live in a src directory. Go ahead and create a src/demo directory. Once created, move into demo and create our first ClojureScript file called static_website.cljs. Now our repo should look like this:


├── src
│   └──  demo
│       └── static_website.cljs
├── style.css
├── deps.edn
└── index.html

Once completed, open static_website.cljs and type this in:

(ns demo.static-website)

(js/console.log "Hello, Github Pages!")

Build development bundle

In the above steps, we have built a minimal site using HTML, CSS and ClojureScript so the last step is to make sure everything is working by running the following command from the root of your project.

clj -m cljs.main -d "demo-clojurescript-gh-pages/out"  -c demo.static-website -r

The above command will take a moment to run. When completed, a browser tab will automatically open and serve your HTM, CSS and ClojureScript. If everything worked you should see a site that looks like this:

screenshot of example hello clojurescript site

Further, if you open your browser console you should see "Hello, Github Pages!"

Build production bundle

At this point we have shown ourselves that our code works locally, now it's time to show the world by deploying our site. Before we deploy, we need to build a production version by executing the following command:

clj -m cljs.main -O advanced -c "demo.static-website"

Once the above is done, rock a git push to your Github project repo and you should see your ClojureScript app live!

Conclusion

As I noted in the beginning, this is a minimal example without 3rd party build tools, frameworks, libraries or conveniences and this the point. There are all kinds of routes you can take, but I hope that I have shown that ClojureScript can be an accessible tool for building static websites.