Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/aventinesolutions/pwdgenerate-reframe

ClojureScript Reagent/Reframe Password Generator
https://github.com/aventinesolutions/pwdgenerate-reframe

Last synced: 23 days ago
JSON representation

ClojureScript Reagent/Reframe Password Generator

Awesome Lists containing this project

README

        

# Aventine Solutions Password Generator
`pwdgenerator-reframe` Version 0.1.4

A [re-frame](https://github.com/day8/re-frame) application designed to generate passwords, Aventine style.

## 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)
- Back end/middleware ([Compojure](https://github.com/weavejester/compojure)): [Clojure](https://clojure.org/)
- CSS compilation ([`lein-less`](https://github.com/montoux/lein-less)): [Less](http://lesscss.org/features/)
* 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)
- Full stack framework: [Compojure](https://github.com/weavejester/compojure)
([Wiki](https://github.com/weavejester/compojure/wiki), [API docs](http://weavejester.github.com/compojure)) ->
[Ring](https://github.com/ring-clojure/ring)
([Wiki](https://github.com/ring-clojure/ring/wiki), [API docs](http://ring-clojure.github.com/ring))
- Client-side routing: [Secretary](https://github.com/gf3/secretary)
* 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)
- CSS compilation: [`lein-less`](https://github.com/montoux/lein-less)
- Test framework: [cljs.test](https://clojurescript.org/tools/testing)
- Test runner: [Karma](https://github.com/karma-runner/karma)
* Development tools
- Debugging: [CLJS DevTools](https://github.com/binaryage/cljs-devtools),
[re-frisk](https://github.com/flexsurfer/re-frisk)
- Emacs integration: [CIDER](https://github.com/clojure-emacs/cider)

#### Directory structure

* [`/`](/../../): project config files
* [`less/`](less/): CSS compilation source files ([Less](http://lesscss.org/features/))
* [`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


```
- 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)
- `css/`: compiled CSS (`lein-less`, can also be
[compiled manually](#compiling-css-with-lein-less))
- `js/compiled/`: compiled CLJS (`shadow-cljs`)
- Not tracked in source control; see [`.gitignore`](.gitignore)
* [`src/clj/pwdgenerator_reframe/`](src/clj/pwdgenerator_reframe/): Backend and middleware source files (Clojure,
[Compojure](https://github.com/weavejester/compojure))
* [`src/cljs/pwdgenerator_reframe/`](src/cljs/pwdgenerator_reframe/): SPA source files (ClojureScript,
[re-frame](https://github.com/Day8/re-frame))
- [`core.cljs`](src/cljs/pwdgenerator_reframe/core.cljs): contains the SPA entry point, `init`
* [`test/cljs/pwdgenerator_reframe/`](test/cljs/pwdgenerator_reframe/): test files (ClojureScript,
[cljs.test](https://clojurescript.org/tools/testing))
- Only namespaces ending in `-test` (files `*_test.cljs`) are compiled and sent to the test runner

### 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)
4. Install [karma-cli](https://www.npmjs.com/package/karma-cli) (test runner):
```sh
npm install -g karma-cli
```
5. Install [Chrome](https://www.google.com/chrome/) or
[Chromium](https://www.chromium.org/getting-involved/download-chromium) version 59 or later
(headless test environment)
* For Chromium, set the `CHROME_BIN` environment variable in your shell to the command that
launches Chromium. For example, in Ubuntu, add the following line to your `.bashrc`:
```bash
export CHROME_BIN=chromium-browser
```
7. Clone this repo and open a terminal in the `pwdgenerator-reframe` 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 Emacs with CIDER

Connect to the browser REPL:
```
M-x cider-jack-in-cljs
```

See
[Shadow CLJS User's Guide: Emacs/CIDER](https://shadow-cljs.github.io/docs/UsersGuide.html#cider)
for more information. Note that the mentioned [`.dir-locals.el`](.dir-locals.el) file has already
been created for you.

#### Connecting to the browser REPL from other editors

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.

### Running Tests

Build the app with the `prod` profile, start a temporary local web server, launch headless
Chrome/Chromium, run tests, and stop the web server:

```shell
% lein karma
# for MingW64 Windows shell
% "/c/Program Files/nodejs/node.exe" /d/workspace/pwdgenerator-reframe/node_modules/karma/bin/karma start ./karma.conf.js --single-run --reporters 'junit,dots'
```

Please be patient; it may take over 15 seconds to see any output, and over 25 seconds to complete.

### Compiling CSS with `lein-less`

Use [Less](http://lesscss.org/features/) to edit styles in `.less` files located in the
[`less/`](less/) directory. CSS files are compiled automatically on [`dev`](#running-the-app)
or [`prod`](#production) build.

Manually compile CSS files:
```sh
lein less once
```

The `resources/public/css/` directory is created, containing the compiled CSS files.

#### Compiling CSS with `lein-less` on change

Enable automatic compiling of CSS files when source `.less` files are changed:
```sh
lein less auto
```

### 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 app
```
### Debug Logging

The `debug?` variable in [`config.cljs`](src/cljs/pwdgenerator_reframe/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 pwdgenerator-reframe.example
(:require [pwdgenerator-reframe.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 with-profile prod uberjar
```

Please be patient; it may take a few seconds to see any output, and over 50 seconds to complete.

The `resources/public/js/compiled` directory is created, containing the compiled `app.js` and
`manifest.edn` files. The `target/` directory is then created, containing the
standalone `pwdgenerator-reframe.jar`.

### Running the Server

[Run the jar](https://github.com/ring-clojure/ring/wiki/Setup-for-production#run-the-server),
setting the port the Ring server will use by setting the environment variable, `port`.

```sh
port=2000 java -jar target/pwdgenerator-reframe.jar
```

If `port` is not set, the server will run on port 3000 by default.

### Deploying to Heroku

1. [Create a Heroku app](https://devcenter.heroku.com/articles/creating-apps):
```sh
heroku create
```

2. [Deploy the app code](https://devcenter.heroku.com/articles/git#deploying-code):

```sh
git push heroku master
```

#### Using Docker for Development
For Windows 10 or MacOS, Docker Desktop is required. For Linux, use the package distribution to install `docker` and
`docker-compose`.

To build the base image load dependencies into the volumes:
```shell
% winpty docker-compose run runner lein deps
% winpty docker-compose run runner npm install
```
It will take some time to build the development image the first time the runner is called. (`winpty` is only required
on windows).

To work on development with all development ports exposed:
```shell
% winpty docker-compose up
```

Once the backend server is up, the REPL can be run like this:
```shell
% winpty docker-compose run runner lein repl :connect runner:8777
```

Tests can be run with Karma like this:
```shell
% winpty docker-compose run runner lein karma
```

### Firebase Configuration

The following environment variables must be set for Firebase to initialize correctly:
```shell
FIREBASE_API_KEY
FIREBASE_AUTH_DOMAIN
FIREBASE_DATABASE_URL
FIREBASE_PROJECT_ID
FIREBASE_STORAGE_BUCKET
FIREBASE_MESSAGING_SENDER_ID
FIREBASE_APP_ID
FIREBASE_MEASUREMENT_ID
```