Getting Started ‐ Repo Setup

Dev Environment for Easy Project Switching

This project uses bash. This follows the cloud environment. The OS manufactures have their idea about what shell to run, but that's for work in their environment. Think of the shell as something that is project dependent. If you are on Windows and don't have bash yet, there's gitforwindows.org. No need to (don't) change your default shell, just get it on your computer and think of it as a project by project configuration. In Visual Studio Code, open your terminnal at the top and it will allows you to select bash for this project.

The .bashrc file in each project's directory can contain custom environment variables and aliases and such for the project. This is where we put secrets becasue the .bashrc file is ignored by .gitignore and won't be put in the repo.

This is also where we put things to setup the environment for this repo.

These steps will make it easy to switch between multiple projects and repos, but automatically running the .bashrc file in a project when you start bash in that directory.

The default setting for the startup terminal in VS Code for this repo has been set to use bash, and to run the local .bashrc file on startup.

If you are not using VS Code, or not using the terminal within VS Code, then you should consider doing this:

In your home (cd ~) directory find or create a .bash_profile on PC or a .profile on mac and add these lines to it. If neither exist, create both just to be sure.

if [ `pwd` != $HOME ] && [[ -f "./.bashrc" ]]; then
    echo running `pwd`/.bashrc
    source ./.bashrc
fi

This works great when you open a terminal in a project directory. But do what it takes to make sure that you are running bash in your terminal. PowerShell, or zsh will not work.

Installing a repo and setting up it's version of Node

Different projects/repos require different versions of Node. It's actually an effort to update versions, and all the related dependencies. We have started using a Node Version Switcher to install/use the corresponding version of Node in each repo. It's also possible to use Node Version Manager, but that's not available on some environments.

Now, create a folder for EnCiv repos (if you don't already have one) and clone the repo into it

mkdir ~/enciv
cd ~/enciv
git clone https://github.com/EnCiv/repo-name.git
cd repo-name

Now, open the repo folder from VS Code.

Create a new a .bashrc file. (Note there is a "." at the beginning of the file name)

If you are on a Mac, add this to the first line of your .bashrc file

export NVS_HOME="$HOME/.nvs"

If you are on Windows, add this to the top of your .bashrc file

function setupNvs {
	export NVS_HOME="$HOME/AppData/Local/nvs/";
	[ -s "$NVS_HOME/nvs.sh" ] && source "$NVS_HOME/nvs.sh" >> /dev/null;
	return 0;
}
setupNvs

Then in either environment also add these lines to the bottom of the file

# get the node version and use NVS to install and switch to it
export NODE_VERSION=`cat .nvmrc`
nvs add $NODE_VERSION
source nvs.sh use $NODE_VERSION

# required so optional dependencies for testing like storybook will be installed
export NODE_ENV=development

# put the repo name here, like civil-pursuit not the letters repo-name
export NPM_PROJECT=repo-name 

# ENV variables to set in the browser based on setting in the server
export BROWSER_ENV="NODE_ENV,HOSTNAME"

Then save the file, open a terminal window. It should look like this the first time:

Downloading [##############################################################################################################################################################################################################################################################] 100%
Extracting  [##############################################################################################################################################################################################################################################################] 100%
Added at: ~\AppData\Local\nvs\node\16.20.1\x64\node.exe
To use this version now: nvs use node/16.20.1/x64
PATH += ~\AppData\Local\nvs\node\16.20.1\x64

~/git/EnCiv/repo (main)

Then, after you get the right version of node (and npm) do this

npm install

Note: If you started out with a different version of node, but are now rolling back, you will need to run npm ci the first time to clean out the node_modules director and rebuild it.

You may see warnings, and warnings about mismatched node and npm versions. You can ignore these, as long as they are warnings.

For the first stages of this project, and for front-end development work we will be focusing on storybook

npm run storybook

A new browser window should pop up like this:

MongoDB

Many repos use MongoDB, if you need a mongodb uri to get started. Cloud.mongodb.com has free accounts, you can go there and follow these instructions

The instructions above are continually getting out of sync with MongoDB's lates UI. Revised instructions would be a welcome contribution that would make it easier for the next developer.

You should end up adding a line like this in your .bashrc file.

export MONGODB_URI="mongodb+srv://user-name:secret-password@cluster0.vwxyz.mongodb.net/db-name?retryWrites=true&w=majority"

Note that it's confusing but user-name and db-name can be anything. You pick them when you create the database, and you use them in this URI string. That's all.

Then you should be able to run the development server. Close your terminal window and open a new one.

npm run dev

It should startup. You will be able to browse to localhost:3011/ What you see is dependent on the repo.

Now you are ready to start developing!