Clarity

Getting started

Set up

Clone this repo, and then in the root directory create a .env file containing:

# Postgres url
DATABASE_URL=postgresql://USERNAME:PASSWORD@localhost:PORT/DB_NAME

# Host and port on which to run the app
PORT=4000
HOST=localhost

# Environment affects the config
NODE_ENV=local-develop

# Facebook Passport config (go to developers.facebook.com)
FB_CLIENT_ID=xxxxx
FB_CLIENT_SECRET=xxxxx
FB_CALLBACK_URL=http://localhost:4000/auth/facebook/callback

# Sentry error tracking config
SENTRY_DSN=https://xxxxx@sentry.io/xxxxx

Run the initial migration to get your development db in the correct state:

sequelize db:migrate:undo:all && sequelize db:migrate

Sublime Text

JsPrettier – This project's CI enforces formatting rules across the codebase with Prettier. To avoid unecessary conflicts and failures when running PRs against CI, it's nice to use the Sublime Text plugin JsPrettier, which autoformats to the rules on save This has the added bonus of allowing you to ignore formatting your code as you write it, which can be an obnoxious time sink. You can find the JsPrettier config here.

Structure

Tests

Unit and integration test files are named module-name.ut.ts and module-name.it.ts, respectively. They are co-located with the module they test. For instance, utilities for formatting dates can be found in utils/date, and the unit tests that exercise these helpers are in utils/date.ut. Mocks are defined in files named module-name.mock.ts.

Functional tests and corresponding test helpers can be found in test/functional. At some point, I'd like to consolidate these into the same naming convention as the unit and integration tests, by having them in module-name.ft.ts, but NightmareJS was flakey as hell and it wasn't worth the effort at the time. Someday...

Here's a useful post about the definitions of each test type and finding the boundaries between them: https://hackernoon.com/low-effort-high-value-integration-tests-in-redux-apps-d3a590bd9fd5.

Testing

Install the Java JDK and set up Selenium.

yarn
brew install selenium-server-standalone
brew install chromedriver

Start the Selenium server and your local dev server.

# In separate terminal windows
selenium-server
yarn start

Run Nightwatch.

nightwatch --config nightwatch.js # Run all tests
nightwatch --config nightwatch.js test/functional/myTest.js # Run one test

Linting

There are several linting rules that can cause CI to fail. Here's a non-comprehensive list (you can find the rest here):

Files don't conform to the Prettier code formatter
- More info about setting up JsPrettier for Sublime above in "Set up"
Files contain console.*
- The default console logger should only be used in debugging/development, so this ensures that they're cleaned up before committing to master
- If you need a real logger, use Hermes.
Files contain express() or bodyParser outside of the http/newApp module
- New express servers will nearly always require certain plugins and configuration, so this check ensures that any new server instances will use the pre-packaged newApp, which handles all that for you

Development

yarn build: Build development server (outputs into /build)
yarn build:prod: Build release (outputs into /dist)
yarn lint: Lint all Typescript files
yarn pretest: Run linter as part of test script
yarn test: More info on Jest config below
yarn test:watch: Run Jest in watch mode
yarn prestart: Bundle the server with development environment before start script
yarn start: Run development server
yarn start:prod: Run production server

Build System

Clarity's Webpack configuration is written in Typescript. By enforcing types in our build system, we can avoid a lot of the mistakes that are famously easy to make when using Webpack.

Live environments

Periodically, we'll want to reset the database for clarity-develop.herokuapp.com:

heroku run "sequelize db:migrate:undo:all && sequelize db:migrate" --app clarity-develop

backus / clarity