Architecture Notes

Front End

See: Getting started frontend documentation

CSS related

• https://github.com/j5bot/bulma-attribute-selectors
• See also very bottom of this page for Flexbox related stuff

Outdated (but potentially still useful) stuff follows:

Folder structure

We're placing the actual "Group Income (Simple Edition)" app under frontend/simple/. This is where the real work is taking place.

The stuff in frontend/ (above frontend/simple/), is mostly ignored for now, and it could be anything really. It should be considered a "totally separate website/project" that represents the main homepage of groupincome.org (a separate github repo altogether, and currently they do not match).

For now, the browserify/webpack stuff is applied only to what's in frontend/simple/, and the stuff in there should not use nginx SSI (server-side includes). Instead it should use EJS's <%- include %> syntax to include things like headers/footers.

Dev stuff

Written in JavaScript ES7 (for async/await; no callbacks!), converted with Babel.

Uses Vue.js and (possibly) Cycle.js frameworks.

Vue.js Resources:

• http://blog.evanyou.me/2015/10/25/vuejs-re-introduction/
• http://vuejs.org/guide/comparison.html
• http://vuejs.org/guide/application.html (contains notes on Babel + building with Webpack/Browserify)
• vue-rx might make Cycle.js irrelevant (need to figure this out)
• http://vuejs.org/guide/plugins.html
• https://github.com/vuejs/awesome-vue (massive collection of plugins and example apps built with Vue)
• forum show & tell — might contain goodies not listed in awesome-vue
• security issues with prior versions
• **Vue TodoMVC — excellent example of .html integration!

Cycle.js Resources:

• !! https://glebbahmutov.com/draw-cycle/
• https://medium.com/@fkrautwald/plug-and-play-all-your-observable-streams-with-cycle-js-e543fc287872
• http://staltz.com/why-react-redux-is-an-inferior-paradigm.html
• https://github.com/vic/awesome-cyclejs
• https://github.com/cyclejs/cycle-time-travel

Alternatively, we could go full Elm, but that seems a bit overkill and (at the moment) would hurt us more than it would help.

Build system

Although Browserify seems to have some advantages as far as Node compatibility goes, Webpack seems to be winning people's favor [1 2 3 4]. Since Webpack doesn't seem to have any major downsides, has received praise from various folks, doesn't require grunt/gulp, and because Vue.js recommends it.

EDIT: However, Webpack is turning out to be a real PITA for using with multiple .html files, so we might go with browserify after all. This article explains the general problem.

Why we went with browserify

• webpack discourages use of grunt, pushes itself as "all-in-one system" but doesn't deliver as nicely as grunt+browserify
• backwards .html support: https://caurea.org/2015/09/16/webpack-is-not-a-static-site-generator.html
• browserify allows simple use of require: https://mattdesl.svbtle.com/browserify-vs-webpack
• see also: https://github.com/vuejs/vuejs.org/issues/252

To explore

• browserify handbook (plus mole)
• http://roots.cx/

Webpack + Babel + Vue resources:

• https://github.com/petehunt/webpack-howto
• http://vuejs.org/guide/application.html
• https://webpack.github.io/docs/list-of-tutorials.html
• vue-loader basic tutorial - essential!
• vue-loader docs: hot reloading, ES2015 and Babel
• excellent Vue + Webpack tutorial
• Webpack and Babel tutorial
• Beginner's Webpack Tutorial — great!
• What to npm install
• babel-loader info for Webpack
• Webpack dev server docs (includes tips on how to combine with an API backend server)
• Electron + Vue + Webpack
• Webpack examples, including Webpack for normal people AKA Webpack with multiple entry points
• Webpack path rewriter (to public paths) + webpack html gen
• Webpack + Grunt
• Vue.js + Webpack + Gulp + Vue Loader "It is something similar to the Vuejs Vue loader example but it uses Gulp."

Avoiding vue-router AKA using multiple .html files:

• https://github.com/bbrewer97202/webpack-multipage-starter
• !! https://github.com/markdalgleish/static-site-generator-webpack-plugin
• Tutorial for using above StaticSiteGeneratorPlugin
• Block by the author of StaticSiteGeneratorPlugin

Sharing resources across app + .html files:

• CommonChunks Plugin tutorial
• exposing globals, importing node_modules etc.
• Multi-entry points

Testing

• Backend tests are currently being done directly in Mocha
• Frontend tests can use Nightmare and/or Karma (which the vue-cli webpack demo gives an example of)

Misc. Useful Things

• Flexboxfroggy! - Fastest way to learn Flexbox!
• What IS Flexbox?
• Flexbox (moar flexbox)
• Flexbox + Vue
• Bulma! - Lightweight modern CSS framework that uses Flexbox (great alt. to bootstrap!)
• Flexbox is entirely logical (almost)
• react-fatigue-dev by @tj