# microtables-frontend

A [re-frame](https://github.com/day8/re-frame) ClojureScript single-page application.

## Project Overview

* Architecture: [Single Page Application (SPA)](https://en.wikipedia.org/wiki/Single-page_application)
* Language: [ClojureScript](https://clojurescript.org/) with [re-frame](https://github.com/day8/re-frame)
* Dependencies
  - UI framework: [re-frame](https://github.com/day8/re-frame) → [Reagent](https://github.com/reagent-project/reagent) → [React](https://github.com/facebook/react)
* Build tools
  - 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 available only during development
  - [`cljs/user.cljs`](dev/cljs/user.cljs): symbols for use during development in the ClojureScript REPL
* [`resources/public/`](resources/public/): SPA root directory
  - [`index.html`](resources/public/index.html): SPA home page
  - `js/compiled/`: compiled CLJS output (not tracked in source control)
* [`src/cljs/microtables_frontend/`](src/cljs/microtables_frontend/): SPA source files

## Environment Setup

1. Install [JDK 11 or later](https://openjdk.java.net/install/)
2. Install [Node.js](https://nodejs.org/)
3. Clone this repo and open a terminal in the `frontend` directory
4. Install dependencies:
    ```sh
    npm install
    ```

### Browser Setup

Disable browser caching when developer tools are open to prevent interference with hot reloading.

Enable custom formatters in Chrome/Chromium DevTools (`Settings → Preferences → Console → Enable custom formatters`) so that [CLJS DevTools](https://github.com/binaryage/cljs-devtools) can display ClojureScript data readably in the console.

## Development

### Running the App

```sh
npm run dev
```

When `[:app] Build completed` appears in the output, browse to [http://localhost:8280/](http://localhost:8280/).

`shadow-cljs` will automatically push ClojureScript code changes to your browser on save. 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) for common pitfalls.

### 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). The running build id is `app` (`:app` in a Clojure context).

### Connecting to the browser REPL from a terminal

1. Connect to the nREPL (port 8777, configured in `shadow-cljs.edn`):
    ```sh
    npx shadow-cljs cljs-repl app
    ```
    Or connect with your editor's nREPL client to `localhost:8777`, then:
    ```clj
    (shadow.cljs.devtools.api/nrepl-select :app)
    ```

### Debug Logging

The `debug?` variable in [`config.cljs`](src/cljs/microtables_frontend/config.cljs) defaults to `true` in dev builds and `false` in prod builds.

## Production

```sh
npm run prod
```

The `resources/public/js/compiled` directory will contain the compiled `app.js` and `manifest.edn` files. The `resources/public/` directory is the complete production web front end.