Yojana

Yojana is a calendar app made using Next.js.

Video Preview

Take a look at the Yojana Youtube Playlist to see the application in action:

Getting Started

Prerequisites

• MySQL 8
• MySQL Shell
• Azure CLI
• Docker
• Node - the current version of Node used is in .nvmrc.
• Yarn
• nvm (optional) - to ensure the correct version of Node is used. Take a look at this to see how to use .nvmrc to automatically switch to the correct version of Node.

Installation

# clone the repository
git clone https://github.com/CPSC319-2022/Yojana.git

# ensure that the correct version of Node is used (optional)
nvm use

# install dependencies
yarn install

MySQL

If you have installed MySQL 8 and MySQL Shell, you should already have a user called root. Run the following command to log in to MySQL Shell.

mysql -u root -p # enter your password

To connect to a remote Azure MySQL database use:

# remove the < > and replace with the correct values
mysql -h <azure fullyQualifiedDomainName> -u <azure administratorLogin> -p # enter your password

See this for more information on interacting with MySQL using MySQL SheÒll.

Environment Variables

You have to set environment variables for development, testing, preview and production environments.

development, preview and production environment variables will be set on Vercel (our hosting platform):

Notes for vercel environment variables:

• NEXTAUTH_URL is the URL of the app. for us, it is https://yojana-main.vercel.app/.
• DB_URL is the URL of the remote database. for us, it is mysql://<azure administratorLogin>:<azure admin password>@<azure fullyQualifiedDomainName>/yojanadb?sslaccept=strict

development and testing environments will be set in the .env and .env.test files.

You will need to create a .env and a .env.test file in the root directory of the project with your environment variables.

You can use the .env.example and .env.test.example files present in the root directory as templates.

To run e2e tests in CI, you will need to store your development and testing environment variables as secrets in GitHub. Just copy the contents of the .env and .env.test files and paste them like this:

Notes for CI environment variables:

• NEXTAUTH_URL is http://localhost:3000/
• DB_URL is set using .env.test

Learn more about environment variables in Next.js.

Setting up Database using Prisma

# Creates database and tables in MySQL according to ./prisma/schema.prisma
yarn prisma:push

Running the App

You should now be able to run the application using the following command:

# start the app on localhost:3000
yarn dev

Development

Scripts

# start the app on localhost:3000
yarn dev

# build the app
yarn build

# analyze the build
yarn build:analyze

# start the app in production mode (after building)
yarn start

# run unit tests
yarn test

# run e2e tests
yarn test:e2e

# run e2e tests in headless mode (no browser window)
yarn test:e2e:headless

# generate coverage report for tests
yarn test:coverage

# run linter
yarn lint

# run formatter
yarn format

# check for formatting errors
yarn format:check

# push database
yarn prisma:push

# migrate database (automatically seeds database if there are new migrations)
yarn prisma:migrate

# reset database (automatically seeds database)
yarn prisma:reset

# run prisma studio (database GUI)
yarn prisma:studio

# format prisma schema
yarn prisma:format

# manually seed database
yarn prisma:seed

# create docker container for MySQL
yarn docker:up

# delete docker container for MySQL
yarn docker:down

Testing

Unit Tests

We use Jest and React Testing Library to write Unit tests.

# run tests
yarn test

You can generate a coverage report by running the following command:

# generate coverage report
yarn test:coverage

This will generate a coverage report in the coverage directory.

E2E Tests

We use Cypress to write E2E tests.

# run tests
yarn test:e2e

You can run the tests in headless mode (no browser window) by running the following command:

# run tests in headless mode
yarn test:e2e:headless

We use Docker to run a MySQL container for our E2E tests. The container is automatically started when you run the E2E tests.

To manually start the container and delete the container when you are done, you can use the following commands:

# start container
yarn docker:up

# delete container
yarn docker:down

Click here to see the configuration for the MySQL container.

GitHub Actions

We use the following GitHub Actions to automate our workflow:

• CI
  • Unit Tests: runs unit tests and generates a coverage report.
  • E2E Tests: runs E2E tests.
  • Format: formats files using Prettier. Make sure to pull the latest changes before making changes to your local branch to avoid merge conflicts.

We also use Vercel to create preview deployments of the app for every PR and branch. This is triggered when a PR is opened or updated.

Pre-commit Hooks

We use Husky and lint-staged to run pre-commit hooks. This ensures that our code is formatted correctly before we commit our code.

Code Style

We use the Prettier with prettier-plugin-tailwindcss to format our code. Please ensure that you have the following configuration in your settings:

Alternatively, you can use to following scripts to manually format your code:

yarn format # to format your code
yarn format:check # to check if your code is formatted correctly

Contributing

• When you make a PR, please make sure that the branch name is in the format your-name/feature-name. For example, john/update-readme.
• Do NOT push directly to main. Always create a new branch and make a PR.
• Always squash and merge PRs to main to keep the commit history clean.

Deployment

We use Azure to deploy our MySQL database and to authenticate users using Azure Active Directory.

We use Vercel to deploy our Next.js app.

Visit this link to see the latest deployed version of the app.

Usage Demos

Note that the following changes were made after these videos were recorded:

• Year (Scroll) has been renamed into Year (Classic)
• Year has been renamed into Year (Vertical)
• A mobile view has been added.

Video Demos

• Project setup: Video, YouTube Mirror

  External References (check back on these on the timestamps mentioned):

  • Creating a local MySQL instance (2:30): MySQL 8, MySQL Shell
  • Setting up Azure AD (6:18): Azure AD, Azure AD with Next-Auth
  • Create an Azure Database for MySQL (16:50): Azure MySQL
  • Docker Installation (25:35): Docker Desktop

• General Website Overview: video, YouTube Mirror

• Calendar View Options: video, YouTube Mirror

• Creating and Adding Entries to Categories: video, YouTube Mirror

• Recurring Dates, Editing and Deleting Categories: video, YouTube Mirror

• Importing entries via CSV: video, YouTube Mirror

• Printing to PDF: video, YouTube Mirror

• Export to iCal: video, YouTube Mirror