This project was bootstrapped with Create React App. The backend is built on top of Firebase. This document is intended to provide you the necessary details to get the mall assassins app code on your local machine and in a state ready for you to run it, contribute your own changes to the code, and integrate those changes into the main version of the app.
The first step to getting started here is to set up your Github account and set up git on your local machine. DO NOT move on to the next section until you have created a pull request.
For Git Aficionados
If you are already familiar with Github and git workflows and are ready to get going, go ahead and fork this repository and then git clone the fork onto your local machine. Make some basic change to this README.md file and submit a pull request (PR) against the main branch of this current repository to prove that you know how these things work. Your PR will get rejected, and once it does, go ahead and move on to the section on setting up npm.
For Less Experienced Git Users
First, try to get a general overview of what git and Github are - ask the person next to you what they are and why they're useful. Make sure you understand the following terms in particular: - git clone - git pull - git branch - git add - git commit - fork - pull request - merge conflictOnce you feel like you have a decent grasp of these ideas, go ahead and move on to the github-setup.md file to actually do the setup.
After finishing the steps in the section above, make sure you also set up this repository as a remote branch so that you can pull the latest changes to the app at all times. To set this repository as a remote branch, run
git remote add upstream [email protected]:Octophi/mall-assassins.git
Then in the future, any time you want to get the latest changes from this repository, run
git pull upstream main
Our project is built in JavaScript using a lot of framework code and special packages and so on. Thankfully, you don't have to go through and download all the individual packages and things that you need in order to get this package to run - that's the beauty of npm. npm (Node Package Manager) is a package manager for JavaScript, widely used for managing and sharing open-source JavaScript libraries and tools. It is often used in web development to install, manage, and distribute packages, which are code modules or libraries that can be used in JavaScript applications (such as ours). To get started on this project, the only thing you need to do is install npm and run the appropriate commands to get your project setup.
We recommend using a Node version manager in order to install Node and npm. This should make your life easier in the long run. Follow our tl;dr instructions below:
Mac Users
- Open Terminal
- Open the Terminal app on your macOS. You can find it in the "Utilities" folder within the "Applications" folder or by searching for "Terminal" using Spotlight.
- Install NVM with Curl
-
In the Terminal, run the following
curl
command to download and install NVM:curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.1/install.sh | bash
This command will download the NVM installation script from the official NVM repository and execute it.
-
Follow the on-screen instructions in the Terminal to complete the NVM installation.
- Verify NVM Installation
-
After the installation is complete, you can verify that NVM was installed successfully by checking the NVM version. Run:
nvm --version
This should display the version of NVM that you installed.
- Install Node.js and npm
-
Now that NVM is installed, you can use it to install Node.js and npm. For example, to install the latest LTS (Long-Term Support) version of Node.js, run:
nvm install --lts
This command will download and install the latest LTS version of Node.js. NVM allows you to install multiple Node.js versions, and you can switch between them as needed.
- Verify Node.js and npm Installation
-
To verify that Node.js and npm have been installed, you can check their versions. Run:
node --version
This command will display the version of Node.js. If it gives you something that looks like a version number, it's probably fine.
To check the version of npm, run:
npm --version
This command will display the version of npm. If it gives you something that looks like a version number, it's probably fine.
That's it! You've successfully installed NVM, Node.js, and npm on your macOS using the Terminal and curl
. You can now use Node.js and npm for your development projects.
** Disclaimer: I had ChatGPT write these steps, I didn't test any of them so if they don't work then yell at me and I'll fix them.
Windows Users
-
Download and Run the NVM Setup Script:
Go to https://github.com/coreybutler/nvm-windows#readme and click "Download Now" in the README. Click on the .exe file to install. Open the downloaded file to start the Setup wizard.
-
Follow the Installation Wizard:
The NVM for Windows Setup wizard will appear. Follow the on-screen instructions to complete the installation. This typically involves agreeing to the license terms, choosing an installation directory, and confirming the installation.
-
Finish the Installation:
After the installation is complete, you will see a confirmation screen. Click "Finish" to exit the installer.
-
Open a New PowerShell Window:
To start using NVM, you need to open a new PowerShell window. You can do this by searching for "PowerShell" in the Windows Start menu and opening the application.
-
Verify NVM Installation:
In the new PowerShell window, you can verify that NVM is installed by running the following command:
nvm version
This should display the version of NVM that you installed.
-
Install Node.js:
To install a specific version of Node.js, you can use NVM. For example, to install the latest LTS (Long-Term Support) version of Node.js, run:
nvm install --lts
This command will download and install the latest LTS version of Node.js.
-
Switch Between Node.js Versions:
You can use NVM to switch between different versions of Node.js. For example, if you want to switch to the LTS version you just installed, run:
nvm use --lts
This sets the LTS version as the active Node.js version.
Now you have NVM for Windows installed, and you can easily manage different versions of Node.js on your machine using PowerShell. You can use the same steps to install additional versions of Node.js or switch between them as needed for your development projects.
** Disclaimer: I had ChatGPT write these steps, I didn't test any of them so if they don't work then yell at me and I'll fix them.
An IDE (Integrated Development Environment) is a software tool that provides programmers with a digital workspace, code editing capabilities, helpful tools, and project management features to make the process of writing, testing, and managing computer programs more efficient and organized. Basically, it helps you code by keeping you organized and giving you neat little tools. I'd recommend developing in an IDE. Which one is up to you, but if you're completely new to this I'd just go ahead and use Visual Studio Code (VSCode) - it's lightweight, pretty intuitive, and enough people use it to help you out. You can find any standard doc online to install it, there's little to set up here so I won't bore you with details.
Ok, you're almost ready to write code! At this point, you should have npm installed and you should have a folder somewhere on your machine with the code for this mall-assassins repository.
- In your terminal, navigate to the directory where you put this mall-assassins code (note: if you don't know how to navigate in the terminal, ask ChatGPT how to navigate in the terminal in Windows/MacOS).
- Once you're in the right folder, run
npm install
. This may take a bit as it will install all the necessary packages to get your code up and running. - After your install finishes, go ahead and run
npm start
. This should automatically open a browser tab at URL localhost:3000 and it should display something that looks like a basic screen with a "Join Room" and "Host Room" option. - Profit. At this stage, you can make changes to the code and it will dynamically update your local server so you can see changes you're making to the app in real time.
If you made it this far, congratulations, you have made it through the setup and are ready to start coding! At this point, check in with the lead of your team on what you can start working on.
You will eventually want to write backend code, including server-side code. For this, you'll want to use Firebase Emulator to test your code locally so you don't have to deploy things directly to production and you can instantly see the effects of the changes you are doing. The setup for this is relatively minimal:
- Install Firebase CLI.
npm install -g firebase-tools
- To start the emulator, run
firebase emulators:start
Note: You need a version of Java at least as new as Java 11 in order to run the emulator.
Below is a list of useful tutorials if you want to familiarize yourself with the technologies used in this app.
- If you can't tell from how I wrote this doc, I think ChatGPT is great for projects like this where you're trying to learn lots of new stuff on the fly (and there's no stakes so there's no cheating concerns).
- If you have any kind of basic question that you just want an answer for, I think a completely acceptable workflow is to ask ChatGPT, see if you understand it, and if not, find someone who looks knowledgeable and ask them to explain what ChatGPT told you.
- Basic blog on web dev
- React documentation: Basic documentation
- Learn React Tutorial: I'd recommend you start here if you've never seen React before
- AngularFire CodeLab: This is using Angular rather than React but you can get some basic ideas of how to call into Firebase from JavaScript