Skip to content

Latest commit

 

History

History

platform-hub-web

README.md

Platform Hub – Web App

Tech summary

An AngularJS 1.5 web app that runs fully client side (served as static assets), with a local development and build stack for easy development, testing and building, as well as communicating with the backend API server (via proxying /api calls from the browser).

Note: You can receive memory issues when running the tests in a docker container.

  • I would recommend 6GB memory for using over 4 GB for docker.
  • Alternatively, run the test in the local environment.
yarn run test

Dev

Prerequisites

Node v6.9.1

nave is a useful way to manage multiple/specific versions of NodeJS.

I would recommend using nvm instead. To setup, install nvm.

Then run:

nvm install 6.9.1

Then run afterwards or any time you need to use node 6.9.1:

nvm use 6.9.1

Alternatively use the following:

To set up:

  • npm install -g nave
  • nave use 6.9.1

NOTE: you'll then need to run nave use 6.9.1 every time you start up a new shell.

Yarn v0.27.5 (for package management)

Yarn provides a more deterministic, safe and reliable mechanism for NodeJS package management (substitute for npm).

The simplest way to set this up is: npm install -g [email protected] though see the install docs for details on potentially better ways. Note that Yarn needs to be available for the version of NodeJS you set up above.

Dev flows

Install dependencies

yarn

NOTE: If you're experiencing issues pulling dependencies from github you might need to update your git configuration:

git config --global url."https://".insteadOf git://

Common tasks

  • yarn run serve – runs a local dev server to serve the app in dev mode (with auto reloading)
  • yarn run build – builds the optimized version of the app for production environments (in /dist)
  • yarn run serve:dist – runs a local server to serve the optimized version of the app (runs the build in the process)
  • yarn run test – runs tests
  • yarn run test:auto – runs tests and then reruns tests automatically on changes

See all available tasks in the scripts section of package.json.

Coding guidelines and source code structure

The structure of this app, and the coding guidelines to work on it, are largely based on:

Important exceptions to the above styleguides:

  • When defining an AngularJS component or directive, place it's corresponding Controller function (assuming it has one) in the same file. This is a conscious decision to keep the logic in components/directives as close as possible to the declaration.
  • All application routes are defined in one file: src/app/app.routes.js.

Key points about structure and guidelines to follow

  • The various app.*.js files in src/app set up everything needed for the overall AngularJS app to run, including any module dependencies, runtime config, routes, constants, etc.
    • The app.module.js is the main "assembly" of the app, and is also where app-wide constants are defined.
  • We break down the app as much as possible into AngularJS modules – in theory, each module could be tested in isolation.
    • We have one top level app module that assembles everything together (as mentioned above).
    • Each individual section – usually a routable part – of the app has it's own folder in src/app (e.g. src/app/home) and has it's own module definition in <section-name>.module.js where all of it's dependencies are described, and all of it's children components, directives, services, factories, etc. are assmebled into the module. Everything needed for this section of app should go in this folder (and broken down into further modules within this folder, if needed).
    • A special app/shared module is used for shared code across the app. You can register stuff directly within this module, or in further modules inside of the app/shared folder (e.g. app/shared/auth).
    • The individual files that provide AngularJS components, directives, services, factories, etc. don't actually know they are AngularJS specific things, as such – they are just functions and objects that make use of AngularJS' conventions, dependency injection and structures, and only get registered in their relevant parent's <foo>.module.js file in to the AngularJS runtime.
  • For CSS we use SASS because it's awesome.
    • The src/app/app.scss file provides app level styling.
    • Individual app sections and shared modules should have their own <foo>.scss file, within their folders, if needed. The dev server and build pipeline will automatically pick these up when building the styles.

Resources