⬅️ Return to course website

Assignment 0: Setup

Released: September 6th

Due: September 13th at 11:59pm ET
Note: Annotations on the reading are due by September 10 at 11:59pm

Introduction

The Hypertext/Hypermedia Cafe is about to open! The first food item we are making: donuts!

On our mission to create the most delicious donuts in the world, we must first 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 - MongoDB, Express, React, Node.

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 and send a message in the #introductions channel on Slack
• Read the course communication guide
• Read and sign the collaboration policy
• Accept assignment0-setup 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 labs! Use code XXMOJD on brownhere.app, and fill out the availability survey. There are 4 mandatory labs throughout the semester. You can see the specific dates on the course calendar, but the times available are:
  • Lab A: Thursday 4-6pm ET
  • Lab B: Friday 3-5pm ET

Note: If you cannot make either of these lab times, please send a Slack direct message to the HTA, Nick.

• Read and annotate As We May Think
  • We will be using a browser extension called hypothes.is for reading and annotation throughout the course. hypothes.is setup instructions are available here.
  • Your own annotations: by Sunday 11:59 pm. Comments on others': due by next class
• Watch Intermedia Demo from 6:54 to 20:26
• Watch Dash Demo

Join the Slack workspace

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 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 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 and Generative AI Policies

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.

CS1951v Development Environment

MERN

In CS1951V, we will be developing full-stack web applications using the MERN stack, which stands for MongoDB, Express, React, and Node/Next.js. 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:

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.

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! Additionally, 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.
• If you are coming from OOP languages (i.e. Java), check out this guide.
• If you are coming from functional languages, check out this guide.

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!

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)
• Git Command Line Interface (CLI)
• Code Styling / Linting

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

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.

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.

Download Visual Studio Code here.

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.

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 editor setup, let’s install the software environment we will be using throughout the semester!

Installing required extensions

To make sure we take full advantage of VS Code, there are a few required and optional extensions to install:

• Prettier [required]
• ESLint [required]
• Todo Tree [recommended]
• GitLens [recommended]
• IntelliCode [recommended]

Feel free to explore other VS Code extensions you like! You can even install custom color themes to style your editor as you wish.

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 onFocusChange. This will autosave any changes you have made whenever you click/tab away.

Set Tab Size

1. Locate the Editor: Tab Size option and input 2. This is the industry standard tab size for JavaScript.

Configure default formatter

1. In the search bar, search the keyword format.
2. Locate the Editor: Default Formatter option and select Prettier - Code formatter.

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.

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 18.x, so we will be using that for this semester. (We recommend using Node 18.17.1 to ensure everyone is on the same version.)

macOS Installation

Using Homebrew
Install Homebrew (if you don't have it already), and run the following in your terminal:
brew install node@18

Using Installer
Download the installer here.

Windows Installation

Using WinGet
Run the following in your terminal:
winget install OpenJS.NodeJS.LTS -v 18.17.1

Using Installer
Download the installer here.

Alternate installation methods (including for Linux) can be found here.

To verify that you have installed Node correctly, run the following line of code in your terminal:
node --version

You should see a version of Node in the terminal.

If there is no error, you have installed Node correctly!

Recommended tool if you need to run multiple versions of Node

We are using the latest LTS version of Node for this course (18.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 18.

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 and a Windows version available here.

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 18: Install the latest version of Node 18
• nvm use 18: Use Node 18

If you are having trouble installing Node, please come to TA hours or post in the #assignments Slack channel.

npm

npm stands for node package manager and it is a package manager for the JavaScript programming language. In other words, it's a package and registry for JavaScript software packages. It was created and maintained by npm, Inc. before the company was acquired by GitHub, a subsidiary of Microsoft. The intention behind developing npm was to help JavaScript developers easily share packaged modules of code and it is relied on by over 11 million developers worldwide today. npm has command line tools to help you install the different packages and dependencies that you will need throughout this course. npm comes preinstalled with Node, so there is no additional setup necessary.

npm Commands that we Use

1. npm install: We use this command to install all modules that are listed on the package.json file and their dependencies. You can use npm i as a shorthand version for this.
2. npm run dev: This command runs the dev script from your package.json file and is used to start a development server.
3. npm run build : This command is used to create an optimized production build. In other words, it creates a build directory with a production build of your app.

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.

Installation

1. Install Git here.
2. To verify that you have installed correctly, the following terminal command should not return an error.
   git --version

If you are running Windows

If you are running Windows, installing Git will include Git Bash. This will be the shell that you should be using throughout the course. The stencil code and handout instructions will assume you are using Git Bash as your shell if you are on Windows.

Git Bash should be an option in your start menu - you should use this instead of using "Command Prompt" or "Powershell". You can also configure Git Bash to be your default shell in the Windows Terminal app or inside of VSCode.

[Optional] GitHub Desktop App

You can use the GitHub Desktop app (in addition to the Git CLI, which is installed above), which is free to download here. 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!

VSCode also has advanced Git source control features built into the editor, just check out the source control tab! The optional GitLens extension adds even more of these features.

If you are having trouble installing Git, 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 unit0-setup on GitHub classroom. If you can successfully run the application after following the steps below, then you’re good to go!

To-Do: Clone the unit0-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 unit0-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: unit0-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!

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.

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 npm commands:
   npm install
npm run dev
   You should see some error messages like this - scary, right?

   ​​​​$ 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`
   ​​​​Error 0: Invalid secret key / secret key not present! Did you forget to add it to the .env file?
   ​​​​[nodemon] app crashed - waiting for file changes before starting...
   

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.

We will be using environment variables throughout the semester, noticeably a Database URI (connection string to your database). You will now create your first environment variables by adding a secret key and a port number.

To-Do

1. Kill the current process by pressing Ctrl+C into the terminal window.
2. Make sure you are in the root of the server folder and use the following command to create the .env file:
   touch .env
3. The following snippet contains the environment variables for this assignment. Open the .env file we just created and then copy and paste this snippet:
   ​​​​SECRET_KEY='hypermedia'
   ​​​​PORT=8000
   

4. Now, let's try it again - run npm run dev now and that should start a server running on localhost:8000.
5. Type the URL localhost:8000 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.

To-Do

1. Open a new terminal and cd into the client folder, which is where the frontend code lives:

   cd client

2. Now that you are in the correct folder, you can install the necessary packages for the project with the following npm command:

   npm install

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.

To-Do

3. The web application can be launched using the npm command:

   npm run dev

   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!

If you cannot get the application to run, please come to TA hours or seek help in the #assignments Slack channel.

Linting

To test whether your linter is working, please navigate to client > src > pages > index.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 you can alternatively run npm run format via the command line to get Prettier to fix all your files.

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!

First, go to client > src > lib > profile.ts and read the IProfile interface. Then, you should properly fill out this placeholder text:

export const profile = {
  role: "student",
  name: "Your name",
  // more key-value pairs...
}

with all your information!

If you need a way to upload your profile or restaurant 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.

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:

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:

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 :)

Our website is hosted at https://cs1951v-2023.vercel.app/. Go check it out!

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!

Don't forget the reading and annotation assignments!