The developers over at Kit have done a great job setting up a Clojure-specific, opinionated web application framework--absolutely, my favorite web server framework.
NOTE: Some of this readme is left in place from their orginal README file. You can compare their project with this to see which text.
Having said that, currently there are some missing examples and documentation for Redis, MySQL and ReactJS setups. I really don't have the time to invest in making modules or profiles for the project. However, I do have time to present a fully working version of Kit under the MIT license with the raw Redis, MySQL, RESTful APIs, nREPL, migrations and React fully integrated.
Some of the code here is probably under other licenses than MIT. I have left all code licenses in place if they were shipped with a license. Check with the original creator of React and other libraries for their current licensing.
The image above is a React component in this deployment that uses 'fetch' to grab the Clojure Kit server's current health status.
You will notice references to 'shogidude.pforacle2024' sprinkled around the code. That is because I derived this code from that project. Also, the React client code is in 'gmclient', short for Game Master Client. There are probably other references I'm not aware of. Replace those references with your own project names, but don't forget to modify paths and namespaces when needed.
I was working on my backrooms.net PFOracle web application for playing RPGs (especially Pathfinder) solo, and realized my custom configuration of the Clojure Kit web framework wasn't really documented any where. Since I strongly believe that if you use opensource software you should give back to the community, I felt I should release this setup for developers that needed some help setting up their Clojure web server.
Some of the things (currently) missing for Clojure Kit, but found here include: raw Redis connections and interactions; Mysql setup with a connection pool; and a deployable React client set up with the ability to use 'npm start' so that you can develop on the server's REPL and the client's React code at the same time.
You will need a running copy of MySQL. For development, I recommend 'localhost' with the standard port. You will find the connection string with username and password in 'resources/system.edn'. DON'T FORGET TO URL ENCODE THE PASSWORD. It will cause you major headaches if you forget.
You will need a running copy of Redis. For this version, I don't have a password setup. I have set up a password on other projects using this library. It's very doable. If you can't figure it out, drop me message, and if I have time, I'll see if I can help. Look in 'resources/system.edn' for the Redis configurations.
You will need all the Node and npm goodies installed. Look up the first few steps of creating React projects. Those instructions almost always explain the process.
You will find the SQL for the server hiding in 'resources/sql/queries.sql'. The function for calling the sample SQL is found in 'shogidude.pforacle2024.integrations.db.system-queries'.
My use of integrant is not great. Forgive me :-)
All the SQL is converted automagically to clojure functions that are retrievable using the query-fn and the SQL name as a key. So, retieving and calling the SQL named 'show-status' is done with the line of code ... '((query-fn) :show-status {})'.
Migrations, both up and down, work just like the Kit website explains. Also, the SQL in 'queries.sql' works the same as the Kit website explains.
Currently, the Kit website explains caching using Redis, but isn't extremely clear on how to use Redis all by itself. Some features of Redis have nothing to do with caching, after all.
The developers over at Kit made a great decision using Carmine for their Redis integrations. You can pretty much do anything that Redis allows with Carmine. However, you might need a little help figuring out how to use Redis directly in your Kit web application.
Check out the 'shogidude.pforacle2024.integrations.redis.redis-system' namespace. Specifically, you want to use the following code to get Kit and Carmine playing nice.
(ns shogidude.pforacle2024.integrations.redis.redis-system
(:require
[integrant.repl.state :as state]
[taoensso.carmine :as car :refer (wcar)]
))
(defn redis-connection []
(:cache/redis state/system))
(defmacro wcar* [& body] `(car/wcar (redis-connection) ~@body))
(defn ping-redis []
(wcar* (car/ping)))
Again, I'm new to Integrant, so there might be better ways of getting (:cache/redis state/system) for your connection. The rest of the code is easily understood when you read through the Carmine Redis library's documentation.
React, often refered to as ReactJS, works great with the Clojure Kit web framework. However, if you are newish to Kit or React, it might be a bit of a challenge getting your server and your development environment set up.
The first trick is to create your React project inside of your Kit project. Your React client becomes a sub-project of your Clojure Kit project.
Next, you need a deploy script. The current one in this project is made for *nix computers including Apple computers. You can easily modify it if you work on a Windows box. Just ask one of the many decent LLMs for help if you get stuck.
You will find the delpoyment script in, 'gmclient/package.json'. CAUTION: The React 'deploy' script deletes the resources/public directory every time it is run, so don't get too attached to anything in that directory.
The other trick is setting up the React project to allow 'npm start' based development to take place while you develop with your running Clojere Kit project. First, I changed the port that 'npm start' runs on to 3002. Next, I added the proxy setting to 'package.json' so that fetching relative paths would work. See the fetch example in HealthStatus.jsx, if you want to see it in action.
If you are using React Router, you need to update the Clojure Kit handler.clj's ig/init-key method. It needs to have the index.html handle 404's. It would need to look something like this.
(defn index-handler []
(-> (resource-response "index.html" {:root "public"})
(http-response/content-type "text/html")))
(defmethod ig/init-key :handler/ring
[_ {:keys [router api-path] :as opts}]
(ring/ring-handler
(router)
(ring/routes
;; Handle trailing slash in routes - add it + redirect to it
;; https://github.com/metosin/reitit/blob/master/doc/ring/slash_handler.md
(ring/redirect-trailing-slash-handler)
(when (some? api-path)
(swagger-ui/create-swagger-ui-handler {:path api-path
:url (str api-path "/swagger.json")}))
(ring/create-default-handler
{
:not-found
(constantly (index-handler))
;(constantly (-> {:status 404, :body "Page not found"}
; (http-response/content-type "text/plain")))
:method-not-allowed
(constantly (-> {:status 405, :body "Not allowed"}
(http-response/content-type "text/plain")))
:not-acceptable
(constantly (-> {:status 406, :body "Not acceptable"}
(http-response/content-type "text/plain")))}))
{:middleware [(middleware/wrap-base opts)]}))
For Clojure's Kit, cd to your Kit project root, and start a REPL in your editor or terminal of choice using the following command for development servers.
clj -M:dev
Start the Clojure Kit server with:
(go)Stop the Clojure Kit server with:
(halt)The default API is available under http://localhost:3000/api
System configuration is available under resources/system.edn.
To reload changes:
(reset)For React, cd to your React project root and use the standard 'npm start'
Configure a REPL following the Cursive documentation. Using the default "Run with IntelliJ project classpath" option will let you select an alias from the "Clojure deps" aliases selection.
Use the cider alias for CIDER nREPL support (run clj -M:dev:cider). See the CIDER docs for more help.
Note that this alias runs nREPL during development. To run nREPL in production (typically when the system starts), use the kit-nrepl library through the +nrepl profile as described in the documentation.
Run clj -M:dev:nrepl or make repl.
Note that, just like with CIDER, this alias runs nREPL during development. To run nREPL in production (typically when the system starts), use the kit-nrepl library through the +nrepl profile as described in the documentation.
If you use the React deploy script to delete the Kit public directory and replace it with your pre-built React client, you can deploy your Kit server as an Uber JAR file, and your React client will come along for the ride. From there, you can containerize it for Docker or your other container-friendly software. Remember to set up firewalls, and remove all passwords and use standard password hiding techniques for keeping your application safe. For example, the nREPL port should NEVER be exposed to the public!