Setup
Running Athens Locally
Video version of this for Mac.
These dependencies are needed to get Athens up and running. To install them, follow the instructions in the links.
Java 11 and Leiningen (Leiningen installs Clojure)
If you want to use Windows Subsystem for Linux (WSL), try this tutorial.
After you've got these dependencies, clone the Git repository to your hard drive:
Then cd athens/
and run the following commands.
Pull JavaScript dependencies:
Pull Java dependencies and build, then start a local HTTP server for Athens:
In another terminal, run:
Another window should open automatically. That's your Athens!
Now make sure you can run code in a REPL and that you know how to use re-frame-10x.
Running in Docker
Docker doesn't work perfectly well anymore, because we are using Electron. Electron requires access to local resources such as resources/index.html
.
If you run yarn run electron .
from your local system, but are running Athens from within Docker, it won't work. Furthermore, if you run yarn run electron .
from within your Docker system, the GUI won't popup on your local system. The workaround would be to sync the resources/
files from Docker to a local folder.
The following command runs Athens in a docker container, but does not provide a workaround to actually run Electron.
Storybook React Components
We are mainly using or are in the process of migrating to React JS components for our frontend, so contributions to our client can be more accessible. Please see up to date docs about Storybook here.
Connecting your REPL
The REPL is one of the core features of Clojure. REPL-driven programming can make you code faster, with less tests and bugs. This video demonstrates this.
Make sure you can run Athens locally before proceeding with this section.
Refer to shadow-cljs editor integration docs for more details.
nREPL port is 8777, as defined in shadow-cljs.edn.
Cursive
https://www.loom.com/share/a2cc5f36f8814704948a57e8277c04e9
CIDER
Calva
In VS Code, run
ctrl+shift+c
andctrl+shift+j
(ctrl+alt+c ctrl+alt+j
in Windows 10) to jack into a repl session.Pick shadow-cljs.
Select
:main
and:renderer
profile for shadow-cljs to watch.Select the
:renderer
build to connect to.In another terminal tab, run
npx electron .
Vim Plugins
Fireplace
Fireplace is a popular Clojure(script) development plugin for Vim (and Neovim) text editor. It's main dependency is the cider-nrepl which already included as a development dependency.
Assume you already executed the commands described above in different terminal sessions and have the Athens instance running. And of course assume you installed vim-fireplace plugin too.
Now open any Clojure file in Vim. This will load vim-fireplace plugin and necessary commands. First, we need to connect Clojure (not Clojurescript yet) runtime;
Clojure part is done. Now to connect Clojurescript runtime with vim-fireplace;
To test your development environment you can try to evaluate some Clojurescript and see the results on Athens running in electron;
You supposed to see an alert on electron app saying "hello!" and your Vim instance would be blocked until you acknowledge the alert message.
If all goes well, now you can see documentation of symbols (binding: K), go to definition (binding: [ C-d) and so fort. See :help fireplace
for more information.
Conjure
Conjure is an interactive environment for evaluating code within your running program for Neovim. Installing Conjure
Its main dependency is the cider-nrepl. Create the following file at ~/.shadow-cljs/config.edn
to add the dependency:
See shadow-cljs docs for more info.
Now that we're set up, lets start the development environment;
Open any Clojurescript file in Neovim. Conjure will connect automatically to the leiningen nrepl server and you should see a temporary floating buffer in the top right corner of your editor showing a successful connection.
To get that buffer back and to keep it open in a horizontal split:
To connect to the Clojurescript runtime;
In the log buffer you should see;
To test your development environment you can try to evaluate some Clojurescript and see the results on Athens running in electron;
You should see an alert in the electron app saying "hello!". All further evaluations will be blocked until you acknowledge the alert message.
Congratulations, you're connected!
To learn more about how to evaluate things with Conjure, please refer to :help conjure
, :help conjure-client-clojure-nrepl
and :ConjureSchool
(an interactive tutorial). See also: [Conjures quickstart guide to Clojurescript](https://github.com/Olical/conjure/wiki/Quick-start:-ClojureScript-(shadow-cljs)) and Clojure
Using re-frame-10x
The right sidebar has re-frame-10x
developer tools. You can toggle it open and close with ctrl-h
, but you must not be focused on a block (ctrl-h has a specific action in some operating systems).
Once you have 10x open, you can hover over blocks' bullets to see some of their datascript data.
By default, 10x is closed everytime Athens starts. Sometimes you want 10x to be open immediately on start. To do, comment out the two lines of JavaScript code in index.html
, where localStorage sets 10x to be closed by default.
Running CI Scripts Locally
After each submitted PR to Athens, GitHub Actions runs the continuous integration workflow declared in .github/workflows/build.yml
. This workflow runs scripts from script/
to test, lint, and build Athens. You can see these workflows in practice in the Actions tab.
However, it's a lot faster if you run these tests locally, so you don't have to submit a PR each time to make sure the workflow succeeds. You may need to install additional dependencies, though.
Testing
No additional installation is needed. Just run this:
The output will look something like this:
Linting
We are linting Clojure code using clj-kondo. Our clj-kondo configuration is in .clj-kondo/config.edn
.
For this linting to work, you will need to install clj-kondo
. Instructions are in clj-kondo
’s installation guide.
To see the problems reported by clj-kondo, run script/lint
. Example run:
Your editor may also be able to integrate with clj-kondo’s output. For example, if you use Calva for VS Code, then clj-kondo’s messages are reported in the Problems panel.
Clojure Styling
To format your code or check that your code is formatted correctly, you will need to use cljstyle
. Instructions for installing it are in cljstyle
’s README.
To check if your Clojure code is formatted correctly, run cljstyle check
. If there is no output and the return code is zero, you’re good. You can also run script/style
, but currently it only works if you’re running Linux.
To reformat all your Clojure files in place, run cljstyle fix
.
Unused Variable Checking
To set this up, first make sure that a global clojure
binary is installed. You won’t necessarily have a clojure
binary installed just because you installed Leiningen.
Next, just run script/carve
. The first time you run it it will download Carve as a dependency, which takes about a minute and outputs lots of messages. On subsequent runs script/carve
won’t output anything unless an unused variable was found.
Git and GitHub Style Guide
Commits
Follow guidelines from Conventional Commits. Specifically, begin each commit with one of the following types:
See some real examples in our commit history.
Issues
Please create issues using our templates. However, you will almost certainly get feedback and help faster in our Discord!
Pull Requests
If your PR is related to other issue(s), reference it by issue number. You can close issues smoothly with GitHub keywords:
This repo only allows those with merge permissions to "Squash and Merge" PRs. This makes reverts easier if they are needed.
Developer Resources
download Sample Athens Databases from our google drive
Last updated