upswyng: A TypeScript repository from amites

UpSwyng is a mobile-ready, digital directory of resources to assist the unhoused and at-risk communities. This is a Code For Boulder project coming soon to Boulder County, Colorado.

Getting Started

If you have any issues getting started using these directions, please see the Troubleshooting section.

Requirements

Make sure you have these tools installed before you begin.

Node.js version 14.3
Docker version 20.10 or above
Yarn

Building your local dev environment

Clone (or fork and clone) this repository and cd into it
Make sure docker is running on your machine. You can check by running docker ps in your terminal
Run yarn start:local

Project Organization

UpSwyng is a monorepo managed with Yarn Workspaces. It consists of five packages all in the packages directory:

common - contains common libraries and utilities used across the other packages
types - contains the TypeScript definitions used across the project
server - a Sapper application with two parts:
- an API server which provides data to the UpSwyng clients
- an admin web interface which uses the Svelte framework to create and modify data for the project
web - contains the React web client
native - contains a proof-of-concept React Native client

Working With Yarn Workspaces

To run a command in a specific package, use the yarn workspace command from the project root. For example, to start the web package development server run:

yarn workspace @upswyng/web start

To run the same command in all workspaces, use yarn workspaces. For instance, to run test in all packages use:

yarn workspaces run test

Typing out the full workspace name can get tedious. You can place aliases in your .bashrc or .profile to save time:

alias @uw="yarn workspace @upswyng/web "

Now you only need @uw start to start the web dev server.

Running tests

When you push a branch up to GitHub, travis will attempt to build the app with your changes and will run our entire test suite to ensure that nothing is broken. It's a good idea to run tests locally before pushing, although it is not required.

If you wish to run tests locally, you will need to ensure that redis-server is available in your path. You can check by running redis-server, and you can install it here or via brew install redis on mac.

Once Redis is installed, run our entire test suite with yarn test.

Troubleshooting

The engine "node" is incompatible with this module.

When running yarn to install project dependencies, you may see a message that looks similar to:

The engine "node" is incompatible with this module. Expected version "^14.3.x". Got "11.15.0".

This just means that your machine's current version of node does not match the version required to run the UpSwyng server, 14.3.x. To fix this you'll need to install and which your current version of Node. nvm is a helpful tool, among others, you could use to easily switch between node versions.

Type Errors

The packages native, server, and web depend on common and types. If you edit common or types, or pull a new commit which contains edits to those packages, they need to be rebuilt. If you do not rebuild, you may see a type error like:

upswyng/packages/server/src/utility/slackbot.ts(76,23): semantic error TS2551:
Property 'DraftApproved' does not exist on type '{ alert_live: any; draft_approved: any;
draft_created: any; draft_deleted: any; resource_issue_reopened: any; resource_issue_resolved: any;
user_permission_changed: any; }'. Did you mean 'draft_approved'?

To fix this, run the script:

yarn build:local-packages

Reset

If nothing you try is fixing your issue, you can totally reset your local environment with yarn reset. After performing a reset, try yarn start:local and see if things work out.

Contributing

Pull requests are welcome and encouraged! Please review and follow our guidelines.

amites/upswyng