Between Two Parens

Deploy ClojureScript to Github Pages

posted on and last updated

Here's a small example of what it looks like to deploy a static website with some ClojureScript to Github Pages. I'll start by introducing some key cocepts and then move into how we actually do the thing.

What is ClojureScript?

ClojureScript, like Elm or Reason, is a compile to js programming language. ClojureScript is different from JavaScript in a few ways.

  • It's a functional language
  • It's a lisp (AKA: Not C style syntax)
  • It's development and design is intentional

Some of the more pragmatic differences

  • The culture of the language avoids breaking changes
  • Write your frontend and backend in one language
  • Out-of-the-box tools to help you solve problems better

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.

A static website is when you write your website in html, css and javascript. You don't need to setup servers, databases or additonal server side code. The benefits:

  • Performance
  • A quick development workflow
  • Easier website security
  • Less expensive to build and host

The downsides are that static websites will not be able to acheive all the cool features of a beefy web app. Often times I will use a static website to prove a concept for an app, host docs or build marketing websites. They are cheap, fast to build and let you prove out concepts.

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.11.1
  . org.clojure/spec.alpha 0.3.218
  . org.clojure/core.specs.alpha 0.2.62

Setting up your HTML

For those that went through the Github Pages quickstart, you should have a repo with a sad, empty index.html. Open your index.html and type the following:

<!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. Type the following into it

: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

This section will now add the absolute minimum requirements to start working with ClojureScript.

Create a file called deps.edn at the same level as our index.html file.

Open the file you've created and type the following code into it.

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

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!

Create src/demo directory. Once created, move into src/demo and create a ClojureScript file called static_website.cljs. Now our repo should look like this:


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

Open static_website.cljs and type the following:

(ns demo.static-website)

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

Open your terminal and run the following command

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

The above command will compile your CLJS into JS. It can take a moment to run. When completed, a browser tab will automatically open and serve your HTML, 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

The above is an example of how we test our code locally. After we're happy with our code, we can build it for production by running the following command:

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

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

Conclusion

As I noted in the beginning, this is a very small example of a ClojureScript project. From here, you can go in many different directions. However, the idea is the same: turn your CLJS code into JS code and ship the JS code.