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.

The rest of this article assumes that you have a Github account. If you don't, no worries. Take a moment and create one for free or just sit back and enjoy the read. For those who want to adventure with me, go through Github's official Github Pages Quickstart for projects and follow it exactly. Note that throughout this post I will have footnotes referencing my live demo project which has each step mirrored by its corresponding commit. Please lean on them if you feel lost at any point

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 .1 org.clojure/spec.alpha 0.2 .176 org.clojure/core.specs.alpha 0.2 .44

Don't worry if your versions are different from mine.

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 >

You will notice that we have added a reference to a js and css file in our HTML. We will add those later. Please also note that where it says "demo-clojurescript-gh-pages" in the script tag above, it should be the name of your Github project repo.

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.773" } } }

If you are coming from JavaScript it can be helpful to think of the deps.edn as similar to package.json . The purpose of this file is to tell clojure which version of ClojureScript we want to use.

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

You want to run the above command from the same place as your deps.edn . Further, if you're curious above the above command and what things like `-d` or `-c` means you can check these out in your terminal by running clj -m cljs.main --help

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:

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

If you are not seeing your ClojureScript in the browser console, please veryify that your index.html file is using your Github project name and the string following the -d in the above command, demo-clojurescript-gh-pages , is also using your Github project name.

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.

Hopefully you did not run into any issues, but if you did please head over to my demo project where I try to identify and help to resolve some gotchas. Experience something new? Please feel free to get in touch and I would be happy to help work through the issue with you.