Contributing

Thank you for your interest in actively participating in the project's development! Please read the Contributor Covenant Code of Conduct and the Contributor License Agreement first.

The project is written in ClojureScript - a compiler for Clojure that targets JavaScript, and is based on re-frame - a framework for building Modern Web Apps in ClojureScript. You should probably take a look at their exceptional documentation first.

Style Guide

We try to follow the Clojure Style Guide as much as possible.

An additional resource about how to name Clojure functions by Stuart Sierra.

In addition to the idiomatic names, we use the following conventions

e           -> event
el, els     -> element, elements
attr, attrs -> attribute, attributes
prop, props -> property, properties
w, h        -> width, height
t           -> time
h, m, s, ms -> hours, minutes, seconds, milliseconds

We also use the following namespace aliases

v  -> views
e  -> events
h  -> handlers
s  -> subs
fx -> effects

If the namespace belongs to a dedicated module, we use module.v.

App structure

Main structure

src\
├── renderer\     <--- Renderer Process
├── electron\     <--- Main Process & Preload script
├── lang\         <--- Translation files
└── worker\       <--- Web Workers

We are trying to split our code under renderer into relatively independent modules, following re-frame's app structure suggestions with some minor additions.

module\
├── core.cljs      <--- entry point
├── db.cljs        <--- schema, validation
├── views.cljs     <--- reagent views
├── events.cljs    <--- event handlers
├── subs.cljs      <--- subscription handlers
├── handlers.cljs  <--- helper functions for db transformations
├── effects.cljs   <--- effect handlers
├── hierarchy.cljs <--- multimethods and hierarchies
├── styles.css     <--- styles
└── README.md      <--- documentation

Re-frame recommendations

Avoid chaining events to create new ones. Always prefer composing pure functions that directly transform the db. That is the whole purpose of handlers namespace.

Use interceptors sparingly. Although they look (and probably are) ingenious, it is hard to write and reason with them. Doing things explicitly, is usually easier to grasp and maintain.

Always use auto-qualified keywords (e.g. ::copy) for subscriptions, events and effects. You can use as-alias to require those namespaces without evaluating the registrations multiple times.

Spec

We use malli to describe the shape of our app db and selectively validate incoming data (e.g. file loading). We also use this spec to generate default values. You can optionally enable full db validation on dev mode (see renderer.dev namespace).

Function inline schemas are used selectively on critical namespaces, like renderer.utils.bounds. Instrumentation is enabled by default on dev environment only.

Useful development shortcuts

Ctrl+Shift+I Toggle devtools
Ctrl+Shift+X Toggle 10x
Ctrl+R Reload app