Assignment 0 | Setup

--- title: Assignment 0 | Setup tags: assignment --- #### [⬅️ Return to course website](https://cs1951v-2022.pages.dev/) # **Assignment 0: Setup** :::info **Released: September 7th** **Due: September 14th, 11:59pm ET** :::      *[HTML]: Hyper Text Markup Language *[W3C]: World Wide Web Consortium *[NPM]: Node Package Manager *[IDE]: Integrated Development Environment *[MERN]: MongoDB, Express, React, NodeJS *[Yarn]: Yet Another Resource Negotiator ## **Introduction** We are on a mission to create the most delicious donuts in the world, but first we must collect all the ingredients! This is the setup assignment, so it is comparatively much shorter than future assignments. You will be setting up the CS1951v development environment for the programming assignments in the course, and ensuring that you are completely setup with everything before we start. Throughout the rest of the course we will be working towards building a hypermedia system, which will require understanding what hypermedia is and what its principles are. We will also become famliar with developing a modern full-stack web application using the MERN stack - <ins>M</ins>ongoDB, <ins>E</ins>xpress, <ins>R</ins>eact, <ins>N</ins>ode. We look forward to getting started! If you have any questions about this assignment, please come to TA hours or message on Slack. Because this is the setup assignment, it's fine for all Slack messages about it to be public. For future assignments, be sure to reference the course communication policy to see if your message should be public or private. ### **Checklist** - [ ] [**Join the Slack**](https://join.slack.com/t/slack-f321941/shared_invite/zt-1erux7ry9-soaiB1VC7MBURx6SNJNngw) and send a message in the ==#introductions== channel on Slack - [ ] Read the **[course communication guide](https://hackmd.io/@CS1951V2022/B116YTq1o)** - [ ] **[Read and sign the collaboration policy](https://forms.gle/ejx968XqaYEzHXdk9)** - [ ] Accept **[assignment0-setup](https://classroom.github.com/a/20_7cWwZ)** on GitHub classroom - [ ] Set up CS1951V Development Environment - [ ] Check that your backend setup is working - [ ] Check that your frontend setup is working - [ ] Deploy your bio to the course website - [ ] Sign up for a lab slot **[here](https://docs.google.com/spreadsheets/d/1mNR-ydgjry1r6U9RKGwZpCnjcBxFC65o3vdacB-24Yg/edit?usp=sharing)**. We will have 4 mandatory labs throughout the semester. You can see the specific dates on the course calendar. The times available are: - Lab A: Thursday 4-6pm ET - Lab B: Friday 3-5pm ET :::warning **Note**: If you cannot make either of these lab times, please send a Slack direct message to the HTA, Brynn. ::: - [ ] Read and annotate [**As We May Think**](https://dl-acm-org.revproxy.brown.edu/doi/pdf/10.1145/227181.227186) - [ ] We will be using a browser extension called hypothes.is for reading and annotation throughout the course. hypothes.is setup instructions are available [**here**](https://docs.google.com/document/d/e/2PACX-1vSDj_dSe6dbdZQlWiRU8Eh1XRqBOEFpVJUhZ5jDCeuOp9_OWTKskEq1vXdJAepobY6qGG9-3gjLCH4B/pub). - [ ] Watch [**Intermedia Demo**](https://youtu.be/bGGxdF0Pn4g?t=414) from 6:54 to 20:26 - [ ] Watch [**Dash Interactive Travel Guide**](https://drive.google.com/file/d/1qnF6nULpCaJvoun7pRlgNyy7R2FEHxFN/view) ## **Join the Slack workspace** <img style="float: left; height: 100px; margin-top: 10px; margin-right: 20px;" src="https://i.imgur.com/c1Jg7jo.gif"> Slack will be our main form of communication throughout the semester. **Course updates and other announcements will be sent through our Slack,** and this Slack workspace will also allow you to interact with other students and the teaching staff. Channels have already been set up for discussion about assignments, labs, readings, and so on. **Slack will also function as our Piazza/EdStem for this course.** Topic-specific questions can be posted in the corresponding channel and will be answered by the staff. Click [**here**](https://join.slack.com/t/slack-f321941/shared_invite/zt-1erux7ry9-soaiB1VC7MBURx6SNJNngw) to join our workspace! Once you do, **send a message in the ==#introductions== channel briefly introducing yourself so we can check you off for joining the Slack.** Include your name, where you're from, and some of your interests / hobbies! Please read the **[course communication guide](https://hackmd.io/PnumehJQTauvK3ljUJRYSA)** for an overview of when to use email versus Slack, when to post questions privately versus publicly, and when to post on Slack versus attending TA hours. ## **Sign the Collaboration Policy** All of our course assignments will be project- and assignment-based, so **it is very important that all of the work that you do this semester is your own.** That being said, general discussions with other students about lecture material and overall concepts are not only allowed but **encouraged**. We want everyone to clearly understand what is allowed to be openly discussed during the semester, so please read closely and complete the collaboration policy agreement **[here](https://forms.gle/aK63TpjTqE45k6BXA)**.  ## **CS1951v Development Environment** ### **MERN** <div style="text-align:center; margin-bottom: 20px"><img style="border-radius:5px; width:400px" src="https://i.imgur.com/IRbmqLO.png" /></div> In CS1951V, we will be developing full-stack web applications using the MERN stack, which stands for MongoDB, Express, React, and Node. The MERN architecture allows you to easily construct a 3-tier architecture (frontend, backend, database) using just JavaScript/TypeScript. The interactions between these technologies are shown below: ![MERN Stack](https://webimages.mongodb.com/_com_assets/cms/mern-stack-b9q1kbudz0.png?auto=format%2Ccompress) Using this stack will allow you to build and deploy full-stack applications easily and efficiently, and will also give you firsthand experience working with these widely used technologies. For a more detailed introduction to the MERN stack, click **[here](https://www.mongodb.com/mern-stack)**. ### **TypeScript** In addition to the MERN stack, we will be using TypeScript as our primary programming language throughout the course. It is more organized than JavaScript, and makes debugging a far easier task for both you and the TAs! TypeScript is a strict syntactical superset of JavaScript. It adds type checking to JavaScript, so if you have experience with JavaScript but not TypeScript, there's no need to worry! Additionaly, by learning and using TypeScript, you will also naturally become more familiar with JavaScript. * If you are already familiar with JS, [check out this guide](https://www.typescriptlang.org/docs/handbook/typescript-in-5-minutes.html). * If you are coming from OOP languages (i.e. Java), [check out this guide](https://www.typescriptlang.org/docs/handbook/typescript-in-5-minutes-oop.html). * If you are coming from functional languages, [check out this guide](https://www.typescriptlang.org/docs/handbook/typescript-in-5-minutes-func.html). :::info :::spoiler **Basic example of TypeScript vs. JavaScript** In JavaScript, the following code would not return an error because it allows accessing properties which aren’t present. In TypeScript, due to the static type checking, it would! ```typescript const ingredients = { sugar: 10, flower: 20, eggs: 2 }; // Why is this NaN? Spelling is hard! const dough = ingredients.sugar + ingredients.folwer + ingredients.eggs; ``` TypeScript would return the following error: ```Property 'folwer' does not exist on type '{ sugar: number, flower: number, eggs: number }'. Did you mean 'flower'?``` ::: ## **Setting Up Your Development Environment** The following will show you how to set up a MERN stack development environment. There are a number of technologies that you will need to install, so please follow the instructions below carefully! The technologies that we will be using in this course include: - Visual Studio Code - Node / Node Package Manager (NPM) - Yarn - Git Command Line Interface (CLI) - Code styling / Linting :::warning **Disclaimer**: If you run into errors during any of the installations found in this assignment, your first step should be to attempt to debug the issue yourself using a search engine. If you cannot figure out the problem yourself, you should then post in Slack or come to TA hours. ::: ### **Visual Studio Code** <div style="text-align:center; margin-bottom: 20px"><img style="border-radius:5px;" src="https://i.imgur.com/kvWdZfy.png" /></div> We highly recommend using Visual Studio Code for course assignments. Visual Studio Code is a code editor that is optimized for building and debugging modern web applications. On top of this, it has built-in Git commands that will make it easier to work with Github Classroom, and has a bunch of incredibly helpful extensions that can be used to improve your workflow. :::warning **Note**: If you don’t have Visual Studio Code, it will be more difficult for the TAs to give you effective support during hours. Also, you will have to configure linting on your own. ::: :::success Download **Visual Studio Code** [here](https://code.visualstudio.com/download). ::: #### Opening a Project and Terminal in Visual Studio Code Once you have Visual Studio Code installed, you can open a project by selecting `File -> Open...`, and then selecting the source folder of a given project. To open a terminal in that project’s directory, select `Terminal -> New Terminal`, and a new terminal window will appear at the bottom of your editor. This terminal can be used to run commands in Visual Studio Code itself without having to leave your editor. :::warning **Note**: You can switch the type of terminal (zsh, bash, PowerShell) by clicking the `down arrow` icon near `+` icon in VS Code terminal. ::: Now that you have your IDE setup, let’s install the software environment we will be using throughout the semester! #### Installing required plugins To make sure we take full advantage of VS Code, there are a few required and optional plugins to install: * [Prettier Eslint](https://marketplace.visualstudio.com/items?itemName=rvest.vs-code-prettier-eslint) [required] * [GitLens](https://marketplace.visualstudio.com/items?itemName=eamodio.gitlens) [optional] * [IntelliCode](https://marketplace.visualstudio.com/items?itemName=VisualStudioExptTeam.vscodeintellicode) [optional] Feel free to explore other VS Code plugins and themes you like! The [GitHub](https://marketplace.visualstudio.com/items?itemName=GitHub.github-vscode-theme) theme is a personal favorite. #### Configuring VS Code This is a **critical step** in setting up your development environment, so don't skip it! *Turn on Autosave* 1. Click the `Manage` ⚙️ icon on the bottom-left side of the editor, and select `Settings`. Alternatively, use `(Ctrl + ,)`. 2. Locate the `Files: Auto Save` option and select `afterDelay`. This will autosave the code whenever you pause editing. You can alternatively use `onFocusChange`, which will autosave whenever you click/tab away. ![](https://i.imgur.com/PyluFhG.png) *Set Tab Size* 1. Locate the `Editor: Tab Size` option and input `2`. This is the industry standard tab size for JavaScript. ![](https://i.imgur.com/FaIi6hL.png) *Configure default formatter* 1. In the search bar, search the keyword `format`. 2. Locate the `Editor: Default Formatter` option and select `Prettier ESlint`. ![](https://i.imgur.com/YD5sJyO.png) 3. Underneath the `Default Formatter` option, locate `Editor: Format On Save` option. Make sure the box is selected, as this will automatically reformat your code and ensure you have the right style on each save. ![](https://i.imgur.com/urRN9Eo.png) ### **Node.js** #### What is Node? Node is a JavaScript runtime built in Chrome’s V8 engine. In other words, **Node is JavaScript outside of the browser**. Traditionally, JavaScript can only be executed within the browser, which is the client-facing side of web applications that every user has access to. However, Node allows you to run JavaScript code on the backend of your application as opposed to on the browser itself. **This allows you to use JavaScript for both the front and backend components of your web applications**, making development much simpler and more straightforward! All Node applications should contain a `package.json` file which specifies: - The packages on which your project depends - Versions of a package that your project can use - Additional metadata such as author, description, and useful scripts for building and running the application We will be using the latest **LTS (Long Term Service)** version of Node.js, as that is the recommended version for most use cases. As of September, the latest LTS is **16.x**, so we will be using that for this semester. (We recommend using Node **16.17.0** to ensure everyone is on the same version.) :::success :::spoiler **macOS Installation** **Using Homebrew** [Install Homebrew](https://brew.sh/) (if you don't have it already), and run the following in your terminal: `brew install node@16` **Using Installer** Download the installer [here](https://nodejs.org/en/). ::: :::success :::spoiler **Windows Installation** **Using WinGet** Run the following in your terminal: `winget install OpenJS.NodeJS.LTS -v 16.17.0` **Using Installer** Download the installer [here](https://nodejs.org/en/). ::: Alternate installation methods (including for Linux) can be found [**here**](https://nodejs.org/en/download/package-manager/). To verify that you have installed Node correctly, run the following line of code in your terminal: `node --version` **If there is no error, you have installed Node correctly!** :::info :::spoiler **Recommended tool if you need to run multiple versions of Node** We are using the latest LTS version of Node for this course (16.x), but we understand if you need to run multiple different versions if you have projects that you are working on that does not support Node 16. Luckily there is a tool that allows us to easily switch between versions of Node / NPM. It is called NVM (Node Version Manager). There is a Linux/MacOS version available [**here**](https://github.com/nvm-sh/nvm), and a Windows version available [**here**](https://github.com/coreybutler/nvm-windows). The README in them is straightforward, and should allow you to easily switch between Node versions. Let us know if you have any questions getting this setup! Here are the basic terminal commands once you have it installed: - `nvm list`: Get a list of the versions currently installed - `nvm install 16`: Install the latest version of Node 16 - `nvm use 16`: Use Node 16 :::warning You will need to reinstall global packages for each version of Node that you have (eg. Yarn)! ::: :::warning If you are having trouble installing Node, please come to TA hours or post in the ==#assignments== Slack channel. ::: ### **Yarn** Yarn stands for `Yet Another Resource Negotiator` and it is a package manager just like npm. It was developed by Facebook and is now open-source. The intention behind developing yarn was to fix performance and security concerns with npm. If you are interested, [here](https://www.imaginarycloud.com/blog/npm-vs-yarn-which-is-better/#security) is an article that outlines the difference between npm and yarn. Yarn is a JavaScript package manager that aims to be speedy, deterministic, and secure. The Yarn Command Line Interface (CLI) will parse the `package.json` file in a Node application and will automatically reach out to the correct online registry and install that package onto your local machine. Its main advantage is its avoidance of any problems related to different versions of Node.js system modules on which the project will be mounted. Yarn should reduce the number of package-management-related issues you will have to deal with throughout the semester. So why need a package manager in the first place? Web applications usually use *a great number* of third-party packages and libraries so we don't have to write everything on our own. Instead of manually installing the packages one-by-one, we use the package manager to automate this process. It's really quick! In order to get consistent installs across machines, Yarn needs more information on the dependencies you configure in your `package.json`. Specifically, Yarn needs to store exactly which versions of each dependency were installed. To do this, Yarn uses a `yarn.lock` file in the root of your project. Your `yarn.lock` file is auto-generated and should be handled entirely by Yarn. As you add/upgrade/remove dependencies with the Yarn CLI, it will automatically update your `yarn.lock` file. Do not edit this file directly as it is quite easy to break something! :::success **Installation** 1. **Install**: To install yarn, run the following `npm` command. It should not matter which directory you are in: `npm install --global yarn` 2. **Verify**: To verify, the following terminal command should not return an error. `yarn --version` If you are having trouble installing Yarn, please come to TA hours or post in the ==#assignments== Slack channel. ::: :::info **Important! Yarn commands we use** 1. **Built in commands**: To install all dependencies: `yarn install` (or use the shortened alias: `yarn`) To add an additional dependency: `yarn add <dependencyName>` To remove an existing dependency: `yarn remove <dependencyName>` 2. **Custom scripts in 1951v** *The custom scripts are all defined in `package.json`.* To start the development server: `yarn start` To identify linting issues in code and autoformat the entire codebase, run: `yarn lint` To see your test coverage, run: `yarn coverage` To format the code base without lint check: `yarn format` ::: ### **Git** Simply put, Git is a version control system that lets you manage and keep track of your source code history. GitHub is a cloud-based hosting service that lets you manage Git repositories. If you are brand new to GitHub, consider watching this **[video](https://www.youtube.com/watch?v=w3jLJU7DT5E)**. :::success **Installation** 1. Install the Git CLI [**here**](https://git-scm.com/downloads). 2. To verify that you have installed correctly, the following terminal command should not return an error. `git --version` ::: :::info :::spoiler **[Optional] GitHub Desktop App** Alternatively, you can use the GitHub Desktop app, which is free to download [here](https://desktop.github.com/). This allows you to work with Github without having to manually run Git commands in your terminal. Some people have a preference for this, so feel free to check it out! [Fork](https://fork.dev/) is a more advanced alternative that you could also consider. VSCode also has advances Git features built into the IDE, just check out the source control tab! ::: :::warning If you are having trouble installing the Git CLI, please come to TA hours or post in the ==#assignments== Slack channel. ::: ## **Checking Your Environment Setup** Now that you have everything installed, we need to check that everything is working properly! To do so, we have created an assignment on GitHub to test both a React frontend environment and a Node/Express backend environment. Accept **[assignment0-setup](https://classroom.github.com/a/20_7cWwZ)** on GitHub classroom. If you can successfully run the application after following the steps below, then you’re good to go! :::success **To-Do**: Clone the `assignment0-setup` repository onto your computer. We recommend that you create a `cs1951v` folder so that this assignment and future ones are organized into one folder. Now that you have made a copy of the `assignment0-setup` repository on your local machine, you can open it with VS Code. Once you have opened it, make sure your active repository is the assignment's root directory - in this case: `assignment0-setup-[<yourGitHubUsername>]`. ::: For this assignment and throughout the course we will be differentiating between the frontend and backend in the same way: **All of the backend code will be stored in a folder called `server` and all of the frontend code will be installed in a folder called `client`.** Our recommendation is to have one terminal open for each whenever you are working on the assignments! <div style="text-align:center; margin-bottom: 20px" ><img style="border-radius:5px; border:solid black 2px;" height=200 src="https://i.imgur.com/2Jaf6cY.png" /></div> :::warning **Disclaimer**: The following repository uses technologies from the MERN stack mentioned above, specifically React for the frontend and Node/Express for the backend. We understand that we haven’t introduced these topics yet. Please do not worry about understanding the entire codebase of these starter applications at this moment as this is just for setup. We will be providing in-depth resources on these topics before you start using these technologies yourself. ::: ### **Backend** To test your backend environment setup, we will test that your setup works with a very basic React application. It contains a simple App file that uses an Express router to send a request to a local address.  :::success TO DO 1. Open a new terminal window. `cd` into the `server` folder, which is where we handle the backend environment in our projects. 2. We want to install the necessary backend applications packages and build the application with the following Yarn commands: `yarn install` `yarn start` You should see some error messages like this - scary, right? ```=bash andy@DESKTOP-JDJ38IV MINGW64 /d/code/setup/server (main) $ yarn start yarn run v1.22.5 $ nodemon src/app.ts [nodemon] 2.0.12 [nodemon] to restart at any time, enter `rs` [nodemon] watching path(s): *.* [nodemon] watching extensions: ts,json [nodemon] starting `ts-node src/app.ts` Server started on port undefined MongoServerError: bad auth : Authentication failed. at MessageStream.messageHandler (D:\code\setup\server\node_modules\mongodb\src\cmap\connection.ts:740:20) at MessageStream.emit (events.js:400:28) at MessageStream.emit (domain.js:470:12) at processIncomingData (D:\code\setup\server\node_modules\mongodb\src\cmap\message_stream.ts:167:12) at MessageStream._write (D:\code\setup\server\node_modules\mongodb\src\cmap\message_stream.ts:64:5) at writeOrBuffer (internal/streams/writable.js:358:12) at MessageStream.Writable.write (internal/streams/writable.js:303:10) at TLSSocket.ondata (internal/streams/readable.js:726:22) at TLSSocket.emit (events.js:400:28) at TLSSocket.emit (domain.js:470:12) { ok: 0, code: 8000, codeName: 'AtlasError' } ``` ::: This happens because we haven't set up the environment variables yet. What is an **environment variable**? Sometimes we have **sensitive information** that we need to include in our code - your password, your SSH key, or even the port number that your app is running on - that's the reason why we keep those information in a seperate `.env` file and call them environment variables. :::success TO DO 1. Kill the current process by pressing `Ctrl+C` into the terminal window. 2. Use the following command to create the `.env` file: - **In Bash/Zsh:** `touch .env` - **In Powershell:** `New-Item .env -type file` 3. The following snippet contains the environment variables we will use this semester. Open the `.env` file we just created and then copy and paste this snippet: ``` DB_USERNAME='student' DB_PASSWORD='cs1951v' PORT=8080 TSC_COMPILE_ON_ERROR=true ESLINT_NO_DEV_ERRORS=true ``` 4. Now, let's try it again - run `yarn start` now and that should start a server running on localhost:8080. 5. Type the URL `localhost:8080` into your web browser. If you see the message **`Your backend setup is complete!`**, then your backend environment is set up correctly! Since we are going to use our backend service later, don't kill the process yet. :::  ### **Frontend** To test your frontend environment setup, we will test that your setup works with a very basic React application. It contains a simple `App.tsx` file that displays some HTML using React. :::success TO DO 1. Open a new terminal and `cd` into the `client` folder, which is where the frontend code lives: `cd client` Now that you are in the correct folder, you can install the necessary packages for the project with the following Yarn command: `yarn install` ::: :::warning Please make sure your backend is running at the same time! Otherwise your frontend will not respond to any request you are about to make. ::: :::success TO DO 2. Create an `.env` file in the `client` folder with `touch .env`. Paste the following variables into the file. TSC_COMPILE_ON_ERROR=true ESLINT_NO_DEV_ERRORS=true 3. The web application can be launched using the Yarn command: `yarn start` **Note**: For people who have used npm before, this is the same as `npm start`. Running this command should automatically open up `localhost:3000` in your web browser. If it doesn’t, you can manually open it by going to the URL `localhost:3000` in your web browser. **Note**: To stop running the React web application hit `Ctrl+C` in the terminal that it is running from. ::: If you see the following message, your frontend environment is correctly set up, and you should be set up for the rest of the course! <div style="text-align:center; margin-bottom: 20px"><img style="border-radius:5px;" src="https://i.imgur.com/l9y1lVq.gif" /></div> :::warning If you cannot get the application to run, please come to TA hours or seek help in the ==#assignments== Slack channel. ::: <div style="text-align:center; margin-bottom: 20px"><img style="border-radius:5px;" src="https://i.imgur.com/x3fElmj.gif" /></div> ### Linting To test whether your linter is working, please navigate to `client > src > App.tsx`. You should see a file that is intentionally formatted incorrectly. **Press `Ctrl+S` to save the file.** You should now see the file going through some stylistic changes, and the code format should look much cleaner. If you do not see any changes after you save, that means some steps in your linting set up is not completed. Please try it again, or enter `yarn lint` to manually perform the reformat. :::warning If you cannot get the linter to run, please come to TA hours or post in the ==#assignments== Slack channel. ::: ### **Deploying your bio to the CS1951v Website!** Now, you can get some practice working with TypeScript objects! But more importantly, you can get to know your classmates. You will be making a basic API call to deploy your profile onto our [**course website**](https://cs1951v-2022.pages.dev/)! First, go to `client > src > api > profile.ts` and read the `IProfile` interface. Then, you should properly fill out this placeholder text: ```typescript= export const profile = { role: "student", name: "Your name", // more key-value pairs... } ``` with all your information! :::warning If you need a way to upload your profile or donut image, you can use https://imgur.com/upload, and then right click the image > "Open image in new tab" to get the direct link URL ending in `.png`, `.jpg`, etc. **Make sure your url ends with `.png`, `.jpg`, `.jpeg`, or `.gif`, otherwise it will not pass our regex check!** Andy and Norm request that your profile picture shows your face, so they can try to learn names and faces. ::: :::info Throughout this course, we will be following the convention of prefixing our interface names with `I`. This helps to distinguish an interface from an instance of that interface (e.g. the interface `IProfile` v.s. the instance `profile`). ::: Now, you can see Typescript in action! To tell the typechecker that `profile` should be an instance of `IProfile`, you can add a *type annotation* like so: ```typescript= export const profile: IProfile = { // your filled out fields... } ``` Now, if you are missing a field or one of the fields is an incorrect type, you will get a *type error*! This is an example of how Typescript prevents bugs and makes your Javascript codebase significantly easier to maintain. If you edited your profile, you will now see a profile and a button at the same `localhost:3000` site that you had set in your frontend environment setup. If you have saved the `profile.ts` file, then it should look something like this: <div style="text-align:center; margin-bottom: 20px"><img style="border-radius:5px;" src="https://i.imgur.com/dAqfM8H.png" /></div> If that works, and if you are happy with your profile, **you are ready to deploy your bio to the course website!** Click the "Deploy your bio to the website" button, and check the course website to see you and your classmates :) :::info Our website is hosted at https://cs1951v-2022.pages.dev/. Go check it out! ::: :::warning If you get an error, check that your `profile` object has valid data for all the required fields. If you're stuck for more than a few minutes, message in the ==#assignments== channel! ::: ### Congrats! You're now set up for the rest of the programming assignments 😎 Happy coding! :::warning Don't forget the reading and annotation assignments! :::