This template is meant to accelerate the initial setup of Clojure/ClojureScript web development projects. It is mostly meant for my own personal use, but you're welcome to pick it up if you think it could be useful to you.
In a nutshell, this is a working combination of http-kit, sente, reagent, and compojure.
The overall structure of the project is:
- a Clojure Ring server that mostly serves static files and some generated HTML.
- a Clojure sente server loop where most of the application logic would live.
- a ClojureScript event loop that manages a single state representation and reacts to UI-driven events as well as server-sent events. Occasional local state via ratoms is acceptable but should be minimal.
Click the fork button (this is a GitHub template), change or remove the copyright notice at the end of this file, change the LICENSE file to an appropriate one (or just remove it if you don't want to publish your work under a license), and rewrite this README.md file to be about your project.
Then:
$ direnv allow
[...]
$ lein repl
[...]
repl=> (go)should open a browser with a running website. For active development, you'll also need:
$ tailwindcss -i tailwind.css -o target/public/css/style.css --watchrunning in another terminal.
This template is a combination of a number of separate pieces. Here is a quick overview.
The project tooling is managed by Nix, with the development environment activated by direnv. Very little familiarity with either Nix or direnv is needed to work on this project, though.
Executable files under bin will be added to your PATH upon activating
direnv. If you need project-level credentials, you can put them in a
.envrc.private file, which will be loaded as a Bash file when creating your
project environment (i.e. export MY_SECRET_ENV_VAR=secret-password).
Note that Nix is used exclusively as a tool manager, which is to say it is providing us with an environment in which we have a known, fixed version of the JVM, Leiningen, and various other shell utilities. We are NOT trying to use Nix to manage our Clojure, JavaScript, or Java dependencies, nor to actually build our application. I have found that Nix yields a tremendously good benefit/effort ratio for tool management, whereas using it for building or dependency management requires a much higher investment in learning Nix itself.
If you're interested, you can read more on my blog for my personal thoughts on how to best use both direnv and Nix in this context.
You should run update-nixpkgs regularly.
This template includes a working configuration for deploying to Heroku. If
you're not interested in deploying to Heroku, you can remove the Procfile and
system.properties file, and may find you no longer have any use for
bin/build either.
Deploying to Heroku should be as simple as creating an application on the Heroku side and pushing this project to it.
This project is set up to use Tailwind for all of its CSS needs. If you don't know about it yet, I strongly recommend taking a look. It synergizes very well with a component approach to ClojureScript development.
This project makes use of figwheel-main. The provided configuration should
work out-of-the-box, but do read the next session on using the REPL. The
css-dirs entry is required to get Figwheel to play nice with Tailwind (as
well as the :clean-targets line in project.clj).
This template is simple enough in its approach to ClojureScript compilation that we do not have more than one Figwheel cofniguration, and just change the optimization level thourgh CLI arguments in bin/build instead of having a dedicated "prod" configuration.
For development, we have a dedicated repl namespace, in which the lein repl
command starts. Running the go function will start a system that:
- Runs Figwheel in watcher mode. Figwheel will refresh the broswer on each ClojureScript and CSS change.
- Reloads server code on file changes. You may still need to refresh your browser manually for this to fully reflect, depending on what you changed.
The project.clj file defines the app name as t and the version
string as app. I do not believe in code-level version strings (or project
names) for standalone applications, but feel free to change both as you like.
This template is not accepting contributions. For your own derived project, feel free to change this section as you like.
Copyright © 2024 Gary Verhaegen.
Licensed under the BSD Zero Clause License. See LICENSE file in the project root, or https://opensource.org/licenses/0BSD for full license information.
The SPDX license identifier for this project is 0BSD.