Sekisei is a re-frame application designed to be a helper of Number Cross Word puzzle solving.
- Architecture: Single Page Application (SPA)
- Languages
- Front end (re-frame): ClojureScript (CLJS)
- CSS compilation (
lein-garden
): Clojure
- Dependencies
- Build tools
- Project task & dependency management: Leiningen
- CLJS compilation, REPL, & hot reload:
shadow-cljs
- CSS compilation:
lein-garden
- Development tools
- Debugging: CLJS DevTools
/
: project config filesdev/
: source files compiled only with the dev profilecljs/user.cljs
: symbols for use during development in the ClojureScript REPL
resources/public/
: SPA root directory; dev / prod profile depends on the most recent buildindex.html
: SPA home page- Dynamic SPA content rendered in the following
div
:<div id="app"></div>
- Customizable; add headers, footers, links to other scripts and styles, etc.
- Dynamic SPA content rendered in the following
- Generated directories and files
- Created on build with either the dev or prod profile
- Deleted on
lein clean
(run by alllein
aliases before building) css/
: compiled CSS (lein-garden
, can also be compiled manually)js/compiled/
: compiled CLJS (shadow-cljs
)- Not tracked in source control; see
.gitignore
- Not tracked in source control; see
src/clj/sekisei/
: CSS compilation source files (Clojure, Garden)src/cljs/sekisei/
: SPA source files (ClojureScript, re-frame)core.cljs
: contains the SPA entry point,init
Use your preferred editor or IDE that supports Clojure/ClojureScript development. See Clojure tools for some popular options.
- Install JDK 8 or later (Java Development Kit)
- Install Leiningen (Clojure/ClojureScript project task & dependency management)
- Install Node.js (JavaScript runtime environment) which should include NPM or if your Node.js installation does not include NPM also install it.
- Clone this repo and open a terminal in the
sekisei
project root directory - (Optional) Download project dependencies:
lein deps
Browser caching should be disabled when developer tools are open to prevent interference with
shadow-cljs
hot reloading.
Custom formatters must be enabled in the browser before CLJS DevTools can display ClojureScript data in the console in a more readable way.
- Open DevTools (Linux/Windows:
F12
orCtrl-Shift-I
; macOS:⌘-Option-I
) - Open DevTools Settings (Linux/Windows:
?
orF1
; macOS:?
orFn+F1
) - Select
Preferences
in the navigation menu on the left, if it is not already selected - Under the
Network
heading, enable theDisable cache (while DevTools is open)
option - Under the
Console
heading, enable theEnable custom formatters
option
- Open Developer Tools (Linux/Windows:
F12
orCtrl-Shift-I
; macOS:⌘-Option-I
) - Open Developer Tools Settings
(Linux/macOS/Windows:
F1
) - Under the
Advanced settings
heading, enable theDisable HTTP Cache (when toolbox is open)
option
Unfortunately, Firefox does not yet support custom formatters in their devtools. For updates, follow the enhancement request in their bug tracker: 1262914 - Add support for Custom Formatters in devtools.
Start a temporary local web server, build the app with the dev
profile, and serve the app with
hot reload:
lein dev
Please be patient; it may take over 20 seconds to see any output, and over 40 seconds to complete.
When [:app] Build completed
appears in the output, browse to
http://localhost:8280/.
shadow-cljs
will automatically push ClojureScript code
changes to your browser on save. To prevent a few common issues, see
Hot Reload in ClojureScript: Things to avoid.
Opening the app in your browser starts a ClojureScript browser REPL, to which you may now connect.
See
Shadow CLJS User's Guide: Editor Integration.
Note that lein dev
runs shadow-cljs watch
for you, and that this project's running build id is
app
, or the keyword :app
in a Clojure context.
Alternatively, search the web for info on connecting to a shadow-cljs
ClojureScript browser REPL
from your editor and configuration.
For example, in Vim / Neovim with fireplace.vim
- Open a
.cljs
file in the project to activatefireplace.vim
- In normal mode, execute the
Piggieback
command with this project's running build id,:app
::Piggieback :app
-
Connect to the
shadow-cljs
nREPL:lein repl :connect localhost:8777
The REPL prompt,
shadow.user=>
, indicates that is a Clojure REPL, not ClojureScript. -
In the REPL, switch the session to this project's running build id,
:app
:(shadow.cljs.devtools.api/nrepl-select :app)
The REPL prompt changes to
cljs.user=>
, indicating that this is now a ClojureScript REPL. -
See
user.cljs
for symbols that are immediately accessible in the REPL without needing torequire
.
Use Clojure and Garden to edit styles in .clj
files located
in the src/clj/sekisei/
directory. CSS files are compiled
automatically on dev
or prod
build.
Manually compile CSS files:
lein garden once
The resources/public/css/
directory is created, containing the compiled CSS files.
Enable automatic compiling of CSS files when source .clj
files are changed:
lein garden auto
See a list of shadow-cljs CLI
actions:
lein run -m shadow.cljs.devtools.cli --help
Please be patient; it may take over 10 seconds to see any output. Also note that some actions shown may not actually be supported, outputting "Unknown action." when run.
Run a shadow-cljs action on this project's build id (without the colon, just app
):
lein run -m shadow.cljs.devtools.cli <action> app
The debug?
variable in config.cljs
defaults to true
in
dev
builds, and false
in prod
builds.
Use debug?
for logging or other tasks that should run only on dev
builds:
(ns sekisei.example
(:require [sekisei.config :as config])
(when config/debug?
(println "This message will appear in the browser console only on dev builds."))
Build the app with the prod
profile:
lein prod
Please be patient; it may take over 15 seconds to see any output, and over 30 seconds to complete.
The resources/public/js/compiled
directory is created, containing the compiled app.js
and
manifest.edn
files.
The resources/public
directory contains the complete, production web front
end of your app.
Always inspect the resources/public/js/compiled
directory prior to deploying the app. Running any
lein
alias in this project after lein dev
will, at the very least, run lein clean
, which
deletes this generated directory. Further, running lein dev
will generate many, much larger
development versions of the files in this directory.
Copyright © 2020 sandmark
Distributed under the Eclipse Public License either version 1.0 or (at your option) any later version.