|
@@ -0,0 +1,203 @@
|
|
|
+# microtables-frontend
|
|
|
+
|
|
|
+A [re-frame](https://github.com/day8/re-frame) application designed to ... well, that part is up to
|
|
|
+you.
|
|
|
+
|
|
|
+## Getting Started
|
|
|
+
|
|
|
+### Project Overview
|
|
|
+
|
|
|
+* Architecture:
|
|
|
+[Single Page Application (SPA)](https://en.wikipedia.org/wiki/Single-page_application)
|
|
|
+* Languages
|
|
|
+ - Front end ([re-frame](https://github.com/day8/re-frame)): [ClojureScript](https://clojurescript.org/) (CLJS)
|
|
|
+* Dependencies
|
|
|
+ - UI framework: [re-frame](https://github.com/day8/re-frame)
|
|
|
+ ([docs](https://github.com/day8/re-frame/blob/master/docs/README.md),
|
|
|
+ [FAQs](https://github.com/day8/re-frame/blob/master/docs/FAQs/README.md)) ->
|
|
|
+ [Reagent](https://github.com/reagent-project/reagent) ->
|
|
|
+ [React](https://github.com/facebook/react)
|
|
|
+* Build tools
|
|
|
+ - Project task & dependency management: [Leiningen](https://github.com/technomancy/leiningen)
|
|
|
+ - CLJS compilation, REPL, & hot reload: [`shadow-cljs`](https://github.com/thheller/shadow-cljs)
|
|
|
+* Development tools
|
|
|
+ - Debugging: [CLJS DevTools](https://github.com/binaryage/cljs-devtools)
|
|
|
+
|
|
|
+#### Directory structure
|
|
|
+
|
|
|
+* [`/`](/../../): project config files
|
|
|
+* [`dev/`](dev/): source files compiled only with the [dev](#running-the-app) profile
|
|
|
+ - [`cljs/user.cljs`](dev/cljs/user.cljs): symbols for use during development in the
|
|
|
+[ClojureScript REPL](#connecting-to-the-browser-repl-from-a-terminal)
|
|
|
+* [`resources/public/`](resources/public/): SPA root directory;
|
|
|
+[dev](#running-the-app) / [prod](#production) profile depends on the most recent build
|
|
|
+ - [`index.html`](resources/public/index.html): SPA home page
|
|
|
+ - Dynamic SPA content rendered in the following `div`:
|
|
|
+ ```html
|
|
|
+ <div id="app"></div>
|
|
|
+ ```
|
|
|
+ - Customizable; add headers, footers, links to other scripts and styles, etc.
|
|
|
+ - Generated directories and files
|
|
|
+ - Created on build with either the [dev](#running-the-app) or [prod](#production) profile
|
|
|
+ - Deleted on `lein clean` (run by all `lein` aliases before building)
|
|
|
+ - `js/compiled/`: compiled CLJS (`shadow-cljs`)
|
|
|
+ - Not tracked in source control; see [`.gitignore`](.gitignore)
|
|
|
+* [`src/cljs/microtables_frontend/`](src/cljs/microtables_frontend/): SPA source files (ClojureScript,
|
|
|
+[re-frame](https://github.com/Day8/re-frame))
|
|
|
+ - [`core.cljs`](src/cljs/microtables_frontend/core.cljs): contains the SPA entry point, `init`
|
|
|
+
|
|
|
+### Editor/IDE
|
|
|
+
|
|
|
+Use your preferred editor or IDE that supports Clojure/ClojureScript development. See
|
|
|
+[Clojure tools](https://clojure.org/community/resources#_clojure_tools) for some popular options.
|
|
|
+
|
|
|
+### Environment Setup
|
|
|
+
|
|
|
+1. Install [JDK 8 or later](https://openjdk.java.net/install/) (Java Development Kit)
|
|
|
+2. Install [Leiningen](https://leiningen.org/#install) (Clojure/ClojureScript project task &
|
|
|
+dependency management)
|
|
|
+3. Install [Node.js](https://nodejs.org/) (JavaScript runtime environment)
|
|
|
+7. Clone this repo and open a terminal in the `microtables-frontend` project root directory
|
|
|
+8. Download project dependencies:
|
|
|
+ ```sh
|
|
|
+ lein deps && npm install
|
|
|
+ ```
|
|
|
+
|
|
|
+### Browser Setup
|
|
|
+
|
|
|
+Browser caching should be disabled when developer tools are open to prevent interference with
|
|
|
+[`shadow-cljs`](https://github.com/thheller/shadow-cljs) hot reloading.
|
|
|
+
|
|
|
+Custom formatters must be enabled in the browser before
|
|
|
+[CLJS DevTools](https://github.com/binaryage/cljs-devtools) can display ClojureScript data in the
|
|
|
+console in a more readable way.
|
|
|
+
|
|
|
+#### Chrome/Chromium
|
|
|
+
|
|
|
+1. Open [DevTools](https://developers.google.com/web/tools/chrome-devtools/) (Linux/Windows: `F12`
|
|
|
+or `Ctrl-Shift-I`; macOS: `⌘-Option-I`)
|
|
|
+2. Open DevTools Settings (Linux/Windows: `?` or `F1`; macOS: `?` or `Fn+F1`)
|
|
|
+3. Select `Preferences` in the navigation menu on the left, if it is not already selected
|
|
|
+4. Under the `Network` heading, enable the `Disable cache (while DevTools is open)` option
|
|
|
+5. Under the `Console` heading, enable the `Enable custom formatters` option
|
|
|
+
|
|
|
+#### Firefox
|
|
|
+
|
|
|
+1. Open [Developer Tools](https://developer.mozilla.org/en-US/docs/Tools) (Linux/Windows: `F12` or
|
|
|
+`Ctrl-Shift-I`; macOS: `⌘-Option-I`)
|
|
|
+2. Open [Developer Tools Settings](https://developer.mozilla.org/en-US/docs/Tools/Settings)
|
|
|
+(Linux/macOS/Windows: `F1`)
|
|
|
+3. Under the `Advanced settings` heading, enable the `Disable 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](https://bugzilla.mozilla.org/show_bug.cgi?id=1262914).
|
|
|
+
|
|
|
+## Development
|
|
|
+
|
|
|
+### Running the App
|
|
|
+
|
|
|
+Start a temporary local web server, build the app with the `dev` profile, and serve the app with
|
|
|
+hot reload:
|
|
|
+
|
|
|
+```sh
|
|
|
+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/](http://localhost:8280/).
|
|
|
+
|
|
|
+[`shadow-cljs`](https://github.com/thheller/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](https://code.thheller.com/blog/shadow-cljs/2019/08/25/hot-reload-in-clojurescript.html#things-to-avoid).
|
|
|
+
|
|
|
+Opening the app in your browser starts a
|
|
|
+[ClojureScript browser REPL](https://clojurescript.org/reference/repl#using-the-browser-as-an-evaluation-environment),
|
|
|
+to which you may now connect.
|
|
|
+
|
|
|
+#### Connecting to the browser REPL from your editor
|
|
|
+
|
|
|
+See
|
|
|
+[Shadow CLJS User's Guide: Editor Integration](https://shadow-cljs.github.io/docs/UsersGuide.html#_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`
|
|
|
+1. Open a `.cljs` file in the project to activate `fireplace.vim`
|
|
|
+2. In normal mode, execute the `Piggieback` command with this project's running build id, `:app`:
|
|
|
+ ```vim
|
|
|
+ :Piggieback :app
|
|
|
+ ```
|
|
|
+
|
|
|
+#### Connecting to the browser REPL from a terminal
|
|
|
+
|
|
|
+1. Connect to the `shadow-cljs` nREPL:
|
|
|
+ ```sh
|
|
|
+ lein repl :connect localhost:8777
|
|
|
+ ```
|
|
|
+ The REPL prompt, `shadow.user=>`, indicates that is a Clojure REPL, not ClojureScript.
|
|
|
+
|
|
|
+2. In the REPL, switch the session to this project's running build id, `:app`:
|
|
|
+ ```clj
|
|
|
+ (shadow.cljs.devtools.api/nrepl-select :app)
|
|
|
+ ```
|
|
|
+ The REPL prompt changes to `cljs.user=>`, indicating that this is now a ClojureScript REPL.
|
|
|
+3. See [`user.cljs`](dev/cljs/user.cljs) for symbols that are immediately accessible in the REPL
|
|
|
+without needing to `require`.
|
|
|
+
|
|
|
+### Running `shadow-cljs` Actions
|
|
|
+
|
|
|
+See a list of [`shadow-cljs CLI`](https://shadow-cljs.github.io/docs/UsersGuide.html#_command_line)
|
|
|
+actions:
|
|
|
+```sh
|
|
|
+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`):
|
|
|
+```sh
|
|
|
+lein run -m shadow.cljs.devtools.cli <action> app
|
|
|
+```
|
|
|
+### Debug Logging
|
|
|
+
|
|
|
+The `debug?` variable in [`config.cljs`](src/cljs/microtables_frontend/config.cljs) defaults to `true` in
|
|
|
+[`dev`](#running-the-app) builds, and `false` in [`prod`](#production) builds.
|
|
|
+
|
|
|
+Use `debug?` for logging or other tasks that should run only on `dev` builds:
|
|
|
+
|
|
|
+```clj
|
|
|
+(ns microtables-frontend.example
|
|
|
+ (:require [microtables-frontend.config :as config])
|
|
|
+
|
|
|
+(when config/debug?
|
|
|
+ (println "This message will appear in the browser console only on dev builds."))
|
|
|
+```
|
|
|
+
|
|
|
+## Production
|
|
|
+
|
|
|
+Build the app with the `prod` profile:
|
|
|
+
|
|
|
+```sh
|
|
|
+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`](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.
|