Development, in-depth documentation

For a high-level overview, see the getting started docs.

The application

The mobile app

Coding conventions

Other conventions

JS

CSS/LESS

CSS class names

Route conventions

TODO: Outdated

Convention is as follows:

Examples

Testing

Strategy:

CI setup

Slowly getting there. Any help/experiences appreciated! #228

Unit tests

…mainly to test Mongo models (example).

…as well some critical bits of Angular frontend (example).

Integration tests

… mainly for the API routes (example).

Clientside Component tests

Run tests

Development tools

Emails

MailDev is there for viewing and testing emails during development.

MailDev will be already running at localhost:1080 but if you need to run it manually, type:

npm run dashboard:mail

Background jobs

Agendash is a dashboard & inspector for Agenda, our job scheduling library.

To run it at localhost:1081, type:

npm run dashboard:jobs

Debugging

The standard node inspector runs on each start for the main app (port 5858) and the worker (port 5859).

To debug using Chrome:

  1. Run ‘npm start’
  2. Open chrome://inspect/#devices. Note the “Remote Target” list should be empty to start
  3. Press “Open dedicated DevTools for Node”
  4. Press “Add connection” and add both localhost:5858 and localhost:5859
  5. They will now appear in “Remote Target” list
  6. Press ‘inspect’ on whichever process you want to debug
  7. You should now have console/profiler etc available.

More information can be found in the NodeJS debug documentation.

Access the server from another device

Analyzing bundles

You can see what goes into the “bundle” that Webpack compiles from all the JS, style and image assets by adding this to your config/env/local/js:

bundleAnalyzer: {
  enabled: true,
  // See https://github.com/webpack-contrib/webpack-bundle-analyzer#options-for-plugin
  options: {},
},

Now when you start the application, bundle analyzer will automatically open new browser tab at http://127.0.0.1:8888/ that shows you information about the bundle.

Coding styles

We apply Eslint rules to our JavaScript files and automatically format them using Prettier. You should install Eslint editor integration as well Prettier editor integration to notice code formatting errors and let the editor autoformat files for you automatically.

Files are autoformatted by Prettier each time you git commit your changes.

Files are also continuously linted as you modify them when running npm start, but if you need to lint all the files separately, run:

npm run lint

To continuously lint files as you modify them, run:

npm run lint:watch

To let Eslint fix linting errors automatically, append -- --fix to either regular lint or -watch command like so:

npm run lint:watch -- --fix

Mock data

There is a data script that the individual mock data scripts with default values to generate mock user data, hosting offers, messages and tribes. It’s highly recommended you run this script after installation, that way you’ll have something to look at.

Run npm run seed - This will add automatically add:

For more custom setups, you can alternatively run the scripts for generating data individually. It is currently recommended that you run them in the sequence provided below.

  1. To add tribes, run npm run seed:tribes 50 — This will create 50 tribes.

    • Run this prior to adding users to add users to tribes automatically

  2. To add users, run npm run seed:users 1000 -- --userNames adminusername — This will create 1000 users and hosting offers. adminusername is optional (a-z0-9) and will create an admin user.

    • It can take up to 5 minutes. Mongoose might complain about duplicates — just ignore these errors.
    • To see the result, log in with your chosen username and password password123.
    • Additional admin usernames are also supported (eg. npm run seed:users 1000 -- --userNames admin1 admin2 admin3)
    • If tribes exist, users will also be added to random tribes

  3. To add messages, run npm run seed:messages 1000 10 — This will create 1000 message threads between random users with up to 10 messages in each thread.

All scripts additionally support --debug and --limit flags showing database debug information and not creating new elements if the number of database items already exist respectively.

Clean database

To drop your database, run:

npm run dropdb

Enable FCM push notifications (optional)

  1. Create FCM account

  2. Go to FCM console and create a new project

  3. Open the project and hit the small gear next to “Overview” at the sidebar so that you get to “project settings” page

  4. Choose “Cloud messaging” tab, copy “Sender ID” number

  5. Choose “Service accounts” tab

  6. Either “create new service account” via “Manage all service accounts” link or choose existing one from the list (for development, “Firebase Admin SDK” account is fine)

  7. Click on the “Generate new private key” button

  8. Choose “json” format and you’ll get a file to download

  9. Add contents from that file to your ./config/env/local.js:

    fcm: {
  senderId: 'PASTE_YOUR_SENDER_ID_NUMBER_HERE',
  serviceAccount: PASTE_YOUR_JSON_CONFIG_HERE
},

  10. To stop Eslint from complaining, you might need to convert double quotes to single quotes. (" → ') or disable Eslint for those lines.

Enable collecting statistics to InfluxDB (optional)

  1. Install InfluxDB v1.0+ and run it (type influxd)

  2. Add InfluxDB configuration to your ./config/env/local.js:

    influxdb: {
  enabled: true,
  options: {
    host: 'localhost',
    port: 8086, // default 8086
    protocol: 'http', // default 'http'
    // username: '',
    // password: '',
    database: 'trustroots'
  }
}

  3. You can observe data through InfluxDB admin panel: localhost:8083 or optionally install Grafana and connect it to InfluxDB.

  4. Read more about the collected data and metrics

Use ImageMagick instead of GraphicsMagick

If you prefer ImageMagick over GraphicsMagick:

  1. In MacOS, you can simply use Homebrew to install it:

    brew install imagemagick

  2. Change imageProcessor setting from ./configs/env/local.js to imagemagic.

Folder layout

You might want to read the folder structure to get a handle on how things are laid out, although we’ve started deviating from it with Angular.js to React migration. A quick summary:

Support