Project Setup Guide

Repo Setup Guide

Repo Folder Structure Overview

Looking at the source, you should see a folder structure that looks similar to the image below. There are a lot of files here, so this section gives some insight into what each file is for and hopes to demystify the magic behind our write, test, commit workflow

• .github/workflows
  • These files define the Github Actions you see configured for our project
  • At the moment there is only validate.yml, which is currently set up to automatically run ESLint (a style checker) and run any tests that we've written
  • In the future, we will also write an Action to automatically publish master branch commits to NPM
• demo
  • Where we will write our example website
• dist
  • The final product of our compilation gets output here when we run yarn build
• node_modules
  • Whenever we run yarn add package-xyz, package-xyz is downloaded from somewhere on the internet and put into this folder
  • You'll see this in almost all node projects
  • If you think about it, the goal of our project is to make it so that someone can do yarn add usecloudfs and have our project get added to their node_modules folder!
• src
  • This is where our react hook code goes
• .eslint.js
  • This contains a configuration for the style rules for our project
  • VS Code should detect this file and highlight violations of these style rules, and can be set up to automatically fix these issues as well
  • Run yarn check-style to see a list of all style issues to confirm or if ES Lint it does not work in you editor
  • Current configuration is very minimal but will be expanded on later
    • Requires tab indentation with an indentation level of 4
    • Limits empty lines at the start and end of a file
    • Enforces no unnecessary semi-colons at the end of lines
  • tsconfig.json and rollup.config.js
    • Rollup is a "JavaScript Bundler". Very briefly, it takes the code we develop, performs some automated transformations, and puts it into and output folder (dist in our case)
    • The current configuration does the following
      • Compiles our TypeScript code into normal JavaScript according to our tsconfig.json configuration file
      • Creates special files with .d.ts file endings so developers using TypeScript can restore the type information we stripped out in the previous step
      • Changes ES Module syntax (import react, { useState} from 'react') into the corresponding CommonJS syntax that a browser can understand
      • Packages code that you yarn added to the project so the output folder is completely self-sufficient
  • jest.config.js
    • Jest is JavaScript testing framework
    • Files that end with .test.[js, jsx, ts, tsx] are test cases that we've written
      • For example, a file named useCounter.test.tsx might be created to test the file useCounter.tsx
    • Run tests with yarn test
  • package.json and yarn.lock
    • node_modules can potentially have a lot of files in it, so sharing it along with your code can be very impractical
    • Instead, information about what packages our code depends on, is stored in package.json
      • Sending a package.json file is sufficient to recreate the entire node_modules folder, since all the package files are hosted on NPM's repository!
    • yarn.lock stores more specific information about the exact versions of each package installed and results in more reproducible dependency lists (although it is technically optional)
    • package.json also defines some short scripts that can be used to run commands
      • For example, running yarn build is the equivalent of running yarn rollup -c and running yarn check-style is the same as running yarn eslint ./src --ext .js,.jsx,.ts,.tsx
    • package.json also has general information about our project, like it's name, GitHub repo, and license
  • .gitignore and .npmignore
    • These files tell git and npm which files to exclude from their respective repositories when pushing changes to them
  • LICENSE and readme.md
    • Contain info about the project

Setup

Prerequisites

• A good code editor with TypeScript support
  • I heavily recommend VS Code because it works really well with TypeScript and is extremely lightweight, meaning it doesn't take a million years to install or launch
• Access to a Linux like shell
  • Mac and Linux users shouldn't have to do anything special beside using their built in terminal
  • If you are on Windows, install WSL 2 by following these steps
    • When you get to Step 6, I recommend using Ubuntu 20.04 as your Linux distribution
    • WSL 2 (Windows Subsystem for Linux) is a Windows 10 feature that lets you use a Linux shell inside Windows, almost like a Virtual Machine
    • Once installed, I highly recommend installing Windows Terminal Preview from the Windows App Store
      • Using this app gives you several benefits over a normal shell
        • Lets you open multiple shells side by side in a single window using the + button along the top
        • Lets you open different types of shells, including CMD, Powershell, and most importantly, any Linux distributions you installed such as Ubuntu
    • Once installed, remember to actually make use of WSL. All of the following will get the same job done behind the scenes:
      • Typing wsl into a regular Windows command prompt
      • Using the shortcut created for your distribution after installing. You should be able to find this shortcut by searching in the Windows search box
      • Opening Windows Terminal Preview and creating a new shell for your WSL 2 distribution
    • You can check to see if the shell you are using is actually using WSL 2 by running uname -r, which should say 4.XXX.XXX-microsoft-standard or running lsb_release -a, which should say your specific distribution name
  • Once you finish, you can use WSL by typing wsl into a regular windows CMD prompt or by searching Ubuntu (or whatever your distro is) in the Window's taskbar search box

Environment Setup

• Install NVM according to these steps
  • You can't use NVM on Windows, so make sure to use WSL 2 as described above if that is the case
• Use NVM to install Node 14
  • You can check you Node version using node --version
• Open a shell and navigate to the folder you keep your projects
  • I do all my react work inside Documents/react
• git clone https://github.com/marinater/useCloudFS.git to clone the repo
• cd useCloudFS
• yarn to install everything. This may take some time
• yarn test as a quick way to see if everything works
  • You should see a lot of tests run, along with green or red boxes depending on whether the tests passed or not

VS Code Setup

• Open this folder in VS Code
  • If you are using WSL, you can navigate to this folder in the shell and type code .. This will open VS Code in WSL mode, which you should be able to see in the bottom right hand corner of the window
    • You can confirm that VS Code is in WSL mode by creating an integrated terminal with the shortcut ctrl + shift + ` and trying to run Linux commands. The text colors of the prompt should also look a bit different from a normal Windows prompt
• Install the ESLint VS Code extension by clicking Install at this link
• Restart VS Code and open the folder again. Open a .tsx file in the src folder and test that the ES Lint extension works by adding multiple new lines at the end of the file
  • You should see a red underline show in the editor stating the ES Lint detected an error
  • If this doesn't show up, you can check ESLint extension settings by opening the Settings UI with ctrl + ,, finding the Extensions tab in the side bar, and then scrolling to ESLint

Write 📝, Test ✅, Deploy 🚩

• All useCloudFS package code and tests will be written in the src folder
• All example code will be written in the demo folder
• Once you have made your changes, run all of our test cases with yarn test GitHub will automatically run these tests as well, so make sure these tests pass before pushing to GitHub
• Make sure there are no uncaught style errors by running yarn check-style
• Push changes to GitHub
  • Never work on the master branch! We will work on the development branch for the most part and only put "production ready" releases on master
  • Each feature you work on should be branched off of development and concisely titled what it focuses on. Look at other branches and follow the naming pattern
  • Make a pull request to development when you are done working on the feature
• Once a push is pulled into master or development, automatic deployment workflows get run to
  • validate style rules
  • run tests
  • update the demo website (only on master branch)
  • publish a new NPM release (only on master branch)