The official website for the BNCHS Robotics Team | FRC Team #5599 - The Sentinels!
The goal is to build a beautiful modern new website, while at the same time allowing students to learn the JavaSccript ecosystem with minimal experience.
Visit the live version over at beta.team5599.com.
Built with TypeScript, NextJS, Redux, and MongoDB
To work on this project, you will need to have git and NodeJS (v12 or higher) installed. If you don't have an editor yet, we recommend getting started with VSCode.
# Clone the project repository
git clone https://github.com/Team5599/BNCHS-Robotics-Website-v5.git
# Navigate into the project directory
cd BNCHS-Robotics-Website-v5
# Install dependencies
npm install
# Run the project locally
npm run dev
# This will start the nextJS application.
# A live version of the website will be available for you to preview at https://localhost:3000/
# This project supports "hot-reloading", meaning any changes you make and save in your editor
# will automatically update in the browser without needing to restart the program or reload the page
Visit http://localhost:3000/ in your browser to ensure the application is working.
If you have any issues with installation, please contact @MichaelRooplall
Contributions by all developers are welcome, regardless of experience.
If you are making a major contribution that adds a new feature, page, or changes a significant amount of code-- please checkout a new branch and make your changes there. You may then submit a pull request for us to review and merge.
ℹ️ Be sure to have read up on the Project Structure and Style Guides and Best Practices when making your contributions.
# Create a new branch and automatically switch to it
git checkout -b BranchFeatureName
# Make your modifications
...
# Stage and commit your changes
git add .
git commit -m "<brief description of changes>"
# Push your new branch and its changes
git push origin BranchFeatureName
ℹ️ New branches and comitted changes will not be visible to other users until your push your branch.
Git is a rather complex topic for new developers. Please don't hesitate to reach out to me with any questions if you get stuck. - @MichaelRooplall
To learn more about Next.js, take a look at the following resources:
- Next.js Documentation - Learn about Next.js features and API.
- Learn Next.js - An interactive Next.js tutorial.
To learn more about React.js, take a look at the following resources:
- React.js Documentation - Learn about React.js features
- Intro to React.js - A introduction to React.js
To learn more about TypeScript, take a look at the following resources:
- TypeScript Documentation - Learn about TypeScript features
- TypeScript for New Programmers - TypeScript from the perspective of a new Developer
- TypeScript for JavaScript Programmers - TypeScript from the perspective of a JavaScript Developer
- TypeScript for Java/C# Programmers - TypeScript from the perspective of a Java/C# Developer
To learn more about Redux, take a look at the following resources:
- Redux Fundamentals - Learn the core concepts, principles, and patterns of Redux
- Redux Tutorials - More resources for learning Redux
To learn more about MongoDB, take a look at the following resources:
- MongoDB - Quick Guide - Overview of concepts for a MongoDB Database
- MongoDB - Useful Resources - Interactive resources for learning MongoDB
Components shared between pages (eg. the Navbar) should be placed in src/components/.
Components that belong to a particular page should be placed in src/components/PAGE/.
Do not place components in src/pages/.
Component files should be placed in folders and named using PascalCase. The .tsx file should be the same name as the folder-- do not use index.tsx to create every component.
Example:
.
└── src/
└── components/
├── Navbar/
│ ├── Navbar.tsx
│ └── navbar.module.css
└── Robots/
└── Robot/
├── Robot.tsx
└── robot.module.css
Global styles or styles pertaining to an entire particular page belong in src/styles/, as opposed to grandular styles for individual components which are placed in stylesheet modules in the component's directory.
Global CSS Variables should be defined in src/styles/global.css
Example:
.
└── src/
└── styles/
├── global.css
├── Home.module.css
└── Robots.module.css
Types shared between components or types shared between the client and the api/backend are placed in /src/@shared-types/
Example:
.
└── src/
└── @shared-types/
├── RobotData.ts
└── SponsorData.ts
Images, fonts, and other assets (inc. 3d files, sounds, etc.) are placed in their respective folders under /public/assets/
Example:
.
└── public/
└── assets/
├── fonts/
│ └── BLADRMF_.TTF
├── images/
│ └── Logo.png
└── models/
└── TheHound.obj
💡 There are libraries that create small, blurred placeholder images (compressed base64 image strings) that we can preload for the user. These placeholders will then fade into the real HD image when loading is completed. Great for faking early responsivity.
This project also uses next/font to automatically optimize and load Inter, a custom Google Font. This functionality came with the NextJS template.
API Keys and Secrets are stored in .env.local . An .env.local.template file is provided as a template, and you can request keys from @MichaelRooplall. These are onlu necessary for migrating the backend from Express to NextJS, you can still do front-end development without them..
Example:
.
├── .env.local
└── .env.local.template
The PORT environmental variable is automatically populated by Heroku, you do not need to add it to your .env.local file.
Design wise, there are currently no concerete examples of what the end product of the websie should look like. In the future, we hope to have a mood board of Figma members can look at to draw inspiration from.
To keep the project code manageable between different developers, we strongly reading up on the the following style conventions:
AirBNB's JavaScript Style Guide AirBNB's React/JSX Style Guide
This project doesn't necessarily follow them to a tee, but they are a good starting point for keeping things clean.
Along with these rules, please consider the following:
- Use react functional components over class components [1]
- Avoid in-line styles whenever possible by creating a stylesheet module. [2]
- When using certain css values across multiple pages, eg. an accent color, define the value once as a css root variable in the global stylesheet and import it wherever you need to use it.
- If you are making a large change or adding a new feature, first checkout a new branch, make your changes, commit the branch, and make a pull request. Someone will review it and merge it in.
- Don't confuse
marginandpadding. Usemarginon elements to space them away from eachother. Usepaddingon elements that act as containers to give "borders" of space. - Use Flexbox and CSS Grid when making complex layouts wherever reasonable. Use the css rule 'gap' for spacing elements inside of a flexbox container rather than margins when possible.
- Remember that in-line styles take precedence over styles applied from stylesheets. Also remember that stylesheets are 'cascading', meaning that latter rules have a high priority and can overwrite former rules.
[1] There are two ways of writing React components. We prefer to use functional components over class components. This may seem challenging for developers coming from object-oriented languages like Java. You can read more about functional components and class components here.
[2] If you like to build your components with in-line styles first, you can definitely do this and then move them to a modular css file later.
The heroku branch is responsible for deploying to our live production server Heroku.
You cannot push directly to the heroku branch. You must create a pull request to merge your branch into the heroku branch. When you create a pull request an ESLint check is run to ensure there are no issues with the updates. If the ESLint check is successful, the pull request can be merged-- this will immediately trigger deployment to the Heroku server.
We use GitHub Actions for our CI/CD pipeline.
Whenever changes are pushed to or merged into the main or heroku branch, GitHub Actions runs our ESLint check.
The ESLint check is responsible for identifying and reporting on patterns found in our code, with the goal of making code more consistent and avoiding bugs. It can catch breaking bugs and unoptimizations before we deploy them to Heroku.
When a pull request passes the ESLint check and is successfully merged into the heroku branch, GitHub Actions runs our Heroku Deploy action, responsible for uploading the code to Heroku.
This project currently uses the BNCHS-Robotics-Server-v3 Express Server to host our API endpoints.
You must be a member of the GitHub organization to view this repo.
In the future, Express routes should be converted to NextJS API routes.
Our current MongoDB database is hosted at cloud.mongodb.com.
Until we have a proper storage solution, backups are currently scattered and hard to locate.
Database models & schemas are currently only found in the v3 Express Server and are being documented and migrated over. If you need access to a type that isn't migrated yet, please ask @Michael Rooplall.
While the project is hosted on Heroku, Cloudflare is responsible for handlign a variety of services:
- Caching
- Auto minificiation
- DNS Management
- This includes handling the beta and delta subdomains and redirection to the blog subdomain, as well as email forwarding for @team5599.com emails.
- Analytics
- DDOS Protection
Our SSL certificates are handled by Heroku.
ℹ️ Did you know we average about 1.29k requests through Cloudflare a day?
- How we handle custom @team5599.com emails. The difference between having custom alias as just a "forwarder" for inbound emails vs. a proper alias for both outbound and inbound emails.
- The v3 website backend has a custom NodeMailer server for sending authentication emails. It can also be adapted to send out mailing lists.
<Grid of contributors>