Müll is brought to you by members of Team Bug bytes
.
We try our best to adhere to the set of rules and guidelines that we've come up as a team to have an efficient workflow. To view our guidelines, refer to our GitHub Wiki.
We use NodeJS 14, npm 6, and Nx to manage our workspace and dependencies. The Nx CLI offers powerful tools for development, and we recommend you install it when contributing to the project.
npm install -g nx
npm i
This project uses pre-commit to enforce formatting and standards. To make sure standards are followed, Travis fails commits which don't comply. This section will detail how to setup pre-commit locally.
pip install pre-commit
pre-commit install
pre-commit run -a
Some secrets and sensitive configuration files are needed to properly operate certains parts of the stack.
Add an .env
file with the required credentials in the root of the project (see docs-and-resources
channel on slack for credentials):
TYPEORM_HOST=<host>
TYPEORM_USERNAME=<username>
TYPEORM_PASSWORD=<password>
...
Add a cypress.env.json
in the apps/mull-ui-e2e/
project folder. See docs-and-resources
channel on slack for our secret key.
{
"ACCESS_TOKEN_SECRET": "<secret-key>"
}
There is a host.env.ts
under the libs/types/src/
folder. This file specifies the hostnames where the applications are currently being hosted and makes it easy to change them. There are a few use cases for this, the most common being if you want to access the application you're hosting on your computer from another device, like your phone. We should not commit changes to this file.
Start the server and client dev server in another terminal to test that everything is working correctly.
nx serve mull-api
nx serve mull-ui
localhost
in your host.env.ts
, then make sure to add the --host
flag so that the webserver can be configured properly to serve the app on the right host
nx serve mull-ui --host 123.123.123.123
Linting is done through the Nx CLI, and uses ESLint.
To lint a project:
nx lint <project>
To lint all projects:
nx run-many --target=lint --all
To lint projects affected by your changes:
nx affected:lint --base=origin/<base-branch>
Testing is done thought the Nx CLI, and uses Jest as the main test runner. Unit tests for our ui project(s) also include snapshot tests using React Test Renderer.
To test a project:
nx test <project>
To update the snapshots of a project:
nx test <project> --updateSnapshot
To test all projects:
nx run-many --target=test --all
To test a specific file:
nx test <project> --test-file <file-name>
To test projects affected by your changes:
nx affected:test --base=origin/<base-branch>
E2E testing is done thought the Nx CLI, and uses cypress.
To run e2e tests for a project:
nx e2e <project>
To run e2e tests in watch mode:
nx e2e <project> --watch
To run e2e tests in headless mode:
nx e2e <project> --headless
To run e2e tests on projects affected by your changes:
nx affected:e2e --base=origin/<base-branch>
Our project is a full stack application which need multiple parts to run properly. This section will detail how to run the project for different usecases.
npm start mull-ui
npm start mull-api
You can serve the database locally for testing, and to avoid interfering with the dev/prod databases.
mysql
image. This image contains the information needed to spin up an instance of a mysql database using docker
docker pull mysql:latest
docker run --name mull-db -e MYSQL_ROOT_PASSWORD=password -p 3306:3306 -d mysql:latest --default-authentication-plugin=mysql_native_password
localhost:3306
. If the test was successful, connect to it.env
:
root=localhost
password=password
, or whatever password you put for MYSQL_ROOT_PASSWORD
mull-dev
(case sensitive). In order to support emojis, set Character Set: utf8mb4
and Collation: utf8mb4_unicode_ci
.You now should have a functioning mysql database running locally, usable for the project!
To stop the container whilst keeping the database changes, run docker stop mull-db
.gql
files located in apps/mull-ui/src/graphql
npm run gen-graphql
apps/mull-ui/src/generated/graphql.tsx
npm run build-ui && npm run build-api
http-server
(or some other web server)
npm i -g http-server
openssl req -newkey rsa:2048 -new -nodes -x509 -days 3650 -keyout key.pem -out cert.pem
http-server dist/apps/mull-ui -p 8080 -c-1
-S
option if using HTTPSnode dist/apps/mull-api/main.js
You can populate the database with random values:
Prerequisite:
seeding:
npm run start mull-api
to update the columns (You don't have to have this running after updating)npm run seed:run
For images to show on the app after seeding:
Download the Images from the image folder in the drive and add them to the upload folder in mull-api.
This only needs to be done once and other images can be added.
Scripts used for running checks on Travis CI can be found under the scripts/
folder.
ci-checks.sh
: This script is meant to be run by Travis CI. It checks the trigger of the current build and run the appropriate checks.check-all.sh
: This script runs lint, test and e2e checks on all projects. To run it:
bash scripts/check-all.sh
check-affected.sh
: This script runs lint, test and e2e checks on affected projects. To run it:
export BASE_BRANCH=develop
, or some other base branchbash scripts/check-affected.sh
We are now caching npm
and pre-commit
for faster build times. However, it is possible for the cache to be spoiled with bad data, or can simply become invalid/obsolete. This would result in inconsistent, or even failed, Travis builds compared to local builds.
As a fix, try clearing the Travis cache. Once cleared, re-run the builds.
When there are merge conflicts in the package-lock.json
file, here are the general steps to take to fix them:
package-lock.json
filepreinstall
script in package.json
. Installing packages with that script without the lock file won't work.npm i
to install the packages again and regenerate the package-lock.json
file.preinstall
script you removed in step 2While you're developing the application, you might want to access the application from your phone. This would allow you to see how it looks on your device or test features such as the camera. Here are some general steps to do this, and some pitfalls to watch out for:
host.env.ts
host to the IP address of your machine--host=your-ip-address
flag.http://your-ip-address:4200
.If you experience issues using the camera on your phone when doing the above steps, this might be due to a few factors. Namely, browsers, by default, don't allow javascript to access your camera over an insecure connection that isn't localhost. Since you're accessing the application through the your-ip-address
hostname, the browser will no longer trust the application and might prevent certain features.
There are ways to remedy this, however. You can create a certificate and host the application over https.
You can also ask your browser to trust your machine's ip address, which might be simpler:
chrome://flags/#unsafely-treat-insecure-origin-as-secure
on your browser (mobile or desktop works fine). You will see the Insecure origins treated as secure
setting. Here, you can whitelist http://your-ip-address:4200
(or other additional items as a comma-separated list), the browser will treat that origin as secure and will no longer block certain features.