Development Workflow

Compiling the server

In order to run the server, you must first compile it. There are a few ways to do this:

# Recompiles when code changes; recommended for development
$ yarn run watch-server

# One-off build
$ yarn run build-server

# Build both server and front-end. Used in production.
$ yarn run build

If you're doing development, it's recommended that you use the yarn run watch-server option.

Whenever you change code on the backend, you'll need to kill the server and run nf start again. This is not necessary when you make frontend code changes.

Workflow

It is highly recommended that you use an IDE with Typescript support. VS Code in particular has excellent Typescript integration. Sublime Text also has a pretty good Typescript plugin.

VS Code can watch your files and recompile them automatically: Go to View > Command Palette > Tasks: Run Task and select build-server.

Modifications to front-end code should appear without the need to reload the current page. Modifications to back-end code require a server restart to take effect.

node-foreman is used for running the server: nf start or running one-off commands nf run. It starts the Node process using the environment variables defined in the .env file, which lets us match the production environment as needed.

Testing

Tests live in /test/ and are executed using the Jest framework.

Run all tests:

$ yarn test

Run a specific test:

$ yarn test -- test/path/to/my.test.js

There are a bunch of other CLI options.

Front-end development

The frontend is built on the Vue framework. Their documentation is excellent and worth the read.

Vue solves the same kinds of problems as Angular or React -- you've got some data, and you need to render it on-screen. Vue does this via components, which is what makes up most of the src/client folder (*.vue). A root component takes in a big blob of data, breaks it up into chunks, renders some of it, and hands the rest off to some sub-components.

Each component is defined in a .vue file. A .vue file has three parts: HTML (template), JavaScript, and CSS. The HTML templates contain special directives for rendering and binding data, including other components, and listening for events. The template syntax documentation is worth a skim. The structure of the JavaScript also relies heavily on the Vue API. The CSS is just CSS.

Deployment

You must be one of the authorized dokku users on the linode instance to deploy. This means your ssh key is in dokku's authorized_keys list. If you want to manage dokku itself, you must also be a sudoer on the linode instance.

You must also add the git remote for the Dokku instance you want to deploy to, e.g. git remote add staging dokku@pepperoni.of-sound-mind.com:roster-staging

Make sure your local repository has what you want to push, e.g. no local changes and up to date with eve-val/master.

If you have added code that uses new environment variables, make sure those are set before deploying. Use dokku config <app> and dokku config:set <app> VAR=value to inspect and set new environment variables.

Push your changes to the Dokku remote: git push staging master

Wait for the dokku output to complete, then check the app at the production URL.

Observability

Contact June/Liz for access to the Honeycomb team that telemetry is sent to.