gen-soln

A platform that connects volunteers and donors to non-profits both locally and nationally, and provides the tools that enable non-profits to manage volunteer opportunities and track donations.

nextjs-starter template

From https://github.com/GTBitsOfGood/nextjs-starter-typescript

Development

Setup

• Clone this repository project on your computer.
• Follow the instructions here to install Git, Node.js (v12.X LTS at least) and the MongoDB Community Server.
• Install the Node.js package manager yarn.
• Navigate to this project in the terminal and run yarn install.
• Run yarn secrets to sync development secrets from Bitwarden and save them to .env.local file locally. Contact a leadership member for the Bitwarden password.
  • Note: If you are using the Windows command prompt, enter yarn secrets:login and then yarn secrets:sync.
• Start your local MongoDB server by running mongod (this command will work if you created aliases as recommended in this article).
• Next, perform migrations on your local database: yarn db:migrate up. You should run this command whenever a new migration is added to the codebase; you can run yarn db:migrate status to check if your local database is up to date.
• Run the dev version of this project by entering yarn dev.

Code/PR Workflow

• Assign an issue to yourself and move it to the "In Progress" pipeline. You will have to use ZenHub, either through the Chrome extension or through their web-app, to do this. Pro-tip: ZenHub will let you filter issues by labels and milestones. Depending on your sub-team, you may want to filter by the "CORE", "DMS" or "VMS" labels and select the current sprint under milestones.
• Create a new branch in the format [NAME]/[ISSUE-NUMBER]-[SHORT_DESCRIPTION] (issue number is optional) by running git checkout -b [BRANCH NAME].
  • example branch name: daniel/48-setup-ci
• Be sure to lint, format, and type-check your code occasionally to catch errors by running yarn lint. Reach out to an EM if you are having problems with the type-checker or are blocked by anything else in general.
• Commit changes and then push your branch by running git push -u origin [BRANCH NAME].
• Create a pull request (PR) on GitHub to merge your branch into develop.
• In your PR, briefly describe the changes, link the PR to its corresponding issue, and request a Senior Developer or EM as a reviewer.

TypeScript

The gen-soln codebase has been primarily written in TypeScript, which is a superset of JavaScript that adds static typing to the language. This means that if you already know how to write JavaScript, you already know how to write TypeScript! Simply rename your .js and .jsx files to .ts and .tsx, respectively.

TypeScript will help you catch bugs early at compile-time and save you significant time from manually debugging your code. If your code compiles, you can be very certain that it will work as expected.

To fully utilize the power of TypeScript, you will have to learn its type system. Use this as a cheat sheet for using TypeScript with React.

While you are encouraged to use TypeScript, you don't have to. Our codebase can be a mix of both TypeScript and JavaScript.

Migrations

TODO: Add a note about migrations, why we are using them, and how to create and run them.

Continuous Deployment

The project uses 3 types of deployments:

1. Preview deployments: These deployments are created on every PR opened to develop and master. We use these deployments to ensure that the PR doesn't break builds and they can be used by the reviewer to test functionality without pulling any changes locally.
2. Staging deployment: On every push to develop, our staging deployment is updated. The deployment uses the same database and environment variables as preview deployments, however, it utilizes a fixed URL, https://gen-soln-staging.vercel.app/, and certain API requests, like those to the Google Maps Autocomplete API, work on staging but not in previews (we can't specify an HTTP referer restriction that applies to all preview deployment URLs). This URL is also used by PMs and designers to track progress and share feedback with engineering.
3. Production deployment: Any push to master updates our production deployment, https://bog-gen-soln.vercel.app/. This deployment uses real data stored in a different database and different environment variables.

Environment Variables

We have three sets of environment variables. Environment variables for staging and production are stored in the production Bitwarden vault, while those for local development are stored in the regular Bitwarden vault. When you run yarn secrets, you only sync the development set. Vercel is provided with all three sets, though it never uses the development environment.

Project Structure

A quick overview of the various folders in this repository:

• components/: Contains almost all of our front-end code. This is where we put our React components, custom hooks, reducers, etc. It has four sub-folders:
  • auth/: Code that is specific to authentication (login page, sign-up, etc.)
  • core/: Will contain components that make up the Horizon Design System, implemented using Material-UI.
  • donation/: Code that is specific to the donation management solution.
  • events/: Will contain code that is specific to the volunteer management solution.
  • Any components or hooks that are not part of the Horizon Design System but are still shared across different parts of the application can be put as root files in this folder.
• pages/: Self-explanatory, see Next.js' docs.
• public/: Stores static files like images, see Next.js' docs.
• requests/: Contains several files, one for each entity/model in our application. We define code for fetching data on the client-side here.
• server/: Contains almost all of our back-end code. This is where we put our Mongoose models, business logic code, and database migration scripts. It has three sub-folders:
  • actions/: This folder also contains one file for each entity/model. Each file contains methods that describe various "actions" associated with that entity, often described through Mongoose queries. Actions can be exposed to the client by creating a corresponding API endpoint. Pro-tip: If you want to run an action from the terminal, see this: #142 (comment).
  • migrations/: Contains database migration scripts. Read more about migrations here.
  • models/: Each file in this folder defines an entity (through Mongoose schemas) in our application and creates the corresponding Mongoose model.
• utils/: A folder that contains miscellaneous code used throughout our application. If you find yourself writing code that is used across the various root folders, put it in a file in utils/.
• config.ts: Not a folder, but a very important file that exports an object used throughout our application. You can think of this file as the single source of ground-truth. You want to use the database URL? import config from "config". You want to know which API endpoints and page routes are available? import config from "config".