setup and init

Author: bradwestfall

Diff for: .gitignore

@@ -0,0 +1,3 @@
+node_modules
+.DS_Store
+build

Diff for: README.md

@@ -0,0 +1,145 @@
+# Welcome to the ReactTraining.com's Node Workshop
+
+Before attending the training, please make sure you install the code (not just clone) and run it to make sure it works. The most common problems for not being able to install and run are related to network configurations at the workshop venue like proxies. If your having these or other issues see the Troubleshooting section below.
+
+## The "What do I need to do before attending the workshop" Checklist:
+
+- [ ] Bring a laptop (don't forget a long power cord).
+- [ ] Install and run this code. If doing `npm start` after installing shows a welcome message, you're all set.
+- [ ] [Become familiar with basic Node and NPM CLI ahead of time](./cli.md)
+- [ ] [Learn the JavaScript syntax that matters the most to React](https://reacttraining.com/blog/javascript-the-react-parts/). Even though this is a "Node" workshop, all the material in that article still applies since it's trying to bring you up to speed with modern JS syntax.
+- [ ] WAIT! Does your company or computer use a VPN or any sort of proxy? That might cause some issues. Someome on your team probably knows how to get around the issues. We can't really help out because the issues surrounding VPN's and Proxies are so diverse and out of our control.
+
+## Install Git, Node, and NPM
+
+If you have any problems with these steps, make sure you see the [Troubleshooting](#troubleshooting) section below.
+
+**Need to install Git?** - http://git-scm.com/downloads
+
+**Need to install Node?** We recommend using [NVM (Node Version Manager)](https://github.com/nvm-sh/nvm) instead of installing from source. Installing from source works, but it's difficult to maintain your node version later on (which is why `nvm` exists). Please see the Windows section for a different install process.
+
+**Windows Users!** Please read the [Windows Users](#windows-users) section below for installing NVM, Node, and WSL.
+
+If you need to verify that you have NVM installed: `nvm --version`. Then install Node:
+
+```sh
+# Installs latest LTS version of node
+# See this page for more install options: https://github.com/nvm-sh/nvm#usage
+$ nvm install node
+
+# lists out the versions of node that you're managing with nvm including
+# which one is the current one in your CLI
+$ nvm list
+```
+
+Verify you have Git, Node, and NPM installed. Installing Node will install NPM.
+
+```sh
+$ git --version
+$ node --version
+$ npm --version
+```
+
+You don't necessarily need the latest version of Node for this workshop.
+
+## Install Workshop Code
+
+Then **clone**, **install**, and **run** the app:
+
+```sh
+# Clone the repo to your local machine (This just clones, it does not "install")
+$ git clone https://github.com/ReactTraining/node-workshop.git
+
+# Whichever directory you run the above command from, that directory should
+# now have a folder called `node-workshop`.
+
+# Change directory to the `node-workshop` folder:
+$ cd node-workshop
+
+# Install and run. Make sure you do these two commands from within the `node-workshop` folder:
+$ npm install
+$ npm start
+
+# If you have issues, read below.
+```
+
+You should be able to run `npm start` and see a welcome message. If you do, you're all set for the workshop.
+
+If something goes wrong, you may need to see the [Troubleshooting](#troubleshooting) section below. We even have a special section for [Windows Users](#windows-users)
+
+## Troubleshooting
+
+A few common problems:
+
+- **You're having problems cloning the repository.** Some corporate networks block port 22, which git uses to communicate with GitHub over SSH. Instead of using SSH, clone the repo over HTTPS. Use the following command to tell git to always use `https` instead of `git`:
+
+```sh
+$ git config --global url."https://".insteadOf git://
+
+# This adds the following to your `~/.gitconfig`:
+[url "https://"]
+  insteadOf = git://
+```
+
+- **You're having trouble installing Node.** We recommend using [nvm](https://github.com/creationix/nvm). nvm makes it really easy to use multiple versions of node on the same machine painlessly. After you install nvm, install the latest stable version of node with the following command:
+
+```sh
+$ nvm use default stable
+```
+
+- **You don't have permissions to install stuff.** You might see an error like `EACCES` during the `npm install` step. If that's the case, it probably means that at some point you did an `sudo npm install` and installed some stuff with root permissions. To fix this, you need to forcefully remove all files that npm caches on your machine and re-install without sudo.
+
+```sh
+$ sudo rm -rf node_modules
+
+# If you installed node with nvm (suggested):
+$ sudo rm -rf ~/.npm
+
+# If you installed node with Homebrew:
+$ sudo rm -rf /usr/local/lib/node_modules
+
+# Then (look ma, no sudo!):
+$ npm install
+```
+
+- **You can't run node with `npm start`.** Make sure you can see a `node_modules` folder at the root. If you can't you need to run `npm install` from the root of the repo.
+
+## Windows Users
+
+There are two days to get NVM (Node Version Manager) -- the "Windows" way and the "Linux" way. Lots of open source command-line tools are written for Linux (Unix) systems so they might be problematic when we try to use their Windows way to do it. But if you can get it to work, it's probably the most simple approach. To use NVM for Windows, follow their instructions here: https://docs.microsoft.com/en-us/windows/dev-environment/javascript/nodejs-on-windows
+
+### Or...
+
+You can use use Windows Subsystem for Linux (WSL) instead of GitBash or PowerShell and essentially host a Linux environment on Windows. This way is a little more involved but we've had lots of success with our Windows audience in our workshop when they do the WSL approach.
+
+- WSL 2 Installation: https://docs.microsoft.com/en-us/windows/wsl/install-win10
+- Node on Windows: https://docs.microsoft.com/en-us/windows/nodejs/setup-on-wsl2
+
+From their docs:
+
+> "There are multiple ways to install Node.js. We recommend using a version manager as versions change very quickly. You will likely need to switch between multiple versions based on the needs of different projects you're working on"
+
+They will recommend you install `nvm` (Node Version Manager). We agree!
+
+<hr />
+
+Not using WSL can have a few problems that might arise in a Windows Environment:
+
+- Permissions issues when attempting to clone the repo. If you are using WSL but usually use another shell, you may want to copy your SSH keys where WSL can access them. [This article explains why this is necessary and how to do it.](https://devblogs.microsoft.com/commandline/sharing-ssh-keys-between-windows-and-wsl-2/)
+- Error after install. Chances are the `npm install` went well but we also do a `postinstall` script to create the `database.json` file. See the [Database](#database) section above for details.
+- If you're able to successfully run the app once but it doesn't start on the subsequent runs, chances are the database port didn't shut down when you recently stopped the app. See the [Database](#database) section above for details.
+- If you do `npm run app` or `npm start` and you get weird errors instead of our menu system, we don't know what that is yet but the only reporters have been using GitBash instead of PowerShell.
+
+<hr />
+
+If you're a Windows user who already does active JS/Node development then you should be good-to-go. Otherwise this section might be able to help.
+
+Consider using [VSCode](https://code.visualstudio.com/download) (A lightweight version of Visual Studio) for our workshops as it is probably more appropriately suited for modern JavaScript development than Visual Studio, Eclipse, IntelliJ, etc. It has a terminal built-in which uses PowerShell by default, but you can configure it to use WSL which is what we recommend.
+
+If you want, you can go into Windows' settings to turn on file extensions. In JavaScript projects, it's common to have a filename like `.gitignore` which would be difficult to see without extensions turned on. It's not required though.
+
+If these instructions for Windows users can be improved, please let us know or make a PR!
+
+## License
+
+This material is available for private, non-commercial use under the [GPL version 3](http://www.gnu.org/licenses/gpl-3.0-standalone.html). If you would like to use this material to conduct your own workshop, please contact us at [hello@reacttraining.com](mailto:hello@reacttraining.com).

Diff for: examples/01-installing/NOTES.md

@@ -0,0 +1,39 @@
+# Node and NPM Commands
+
+When you install Node, it comes with NPM (Node Package Manager)
+
+```sh
+# Get the node version (or use `node --version`)
+# Also use this just to check if node is installed
+node -v
+
+# Get the npm version or check to see if installed
+npm -v
+```
+
+You can install node from source, but if you're able to, we recommend using NVM (see below).
+
+By the way, Even numbers are LTS in Node. It's probably best to install the latest LTS active version. See https://nodejs.org/en/about/releases/ for more details.
+
+## NVM (Node Version Manager)
+
+This is an unofficial tool to help install and manage different versions of Node on one machine. From their docs:
+
+> nvm is a version manager for node.js, designed to be installed per-user, and invoked per-shell. nvm works on any POSIX-compliant shell (sh, dash, ksh, zsh, bash), in particular on these platforms: unix, macOS, and windows WSL.
+
+If you need help installing nvm on Windows, you'll need WSL. See our main [Readme](./README.md) and https://docs.microsoft.com/en-us/windows/nodejs/setup-on-wsl2
+
+For how to install and use nvm: https://github.com/nvm-sh/nvm
+
+```sh
+# List out the node versions you have, and see which one is currently being used:
+nvm list
+
+# Switch to 18
+nvm use 18
+
+# Install 20
+nvm install 20
+```
+
+Also explain how NVM defaults work

Diff for: examples/02-npm-basics/NOTES.md

@@ -0,0 +1,178 @@
+# NPM Basics
+
+"80/20 rule"
+
+In reality for NPM it's more like the 95/5 rule. You only need to know 5% of the things NPM can do in order to do the vast majority of your work.
+
+Start an NPM project: `npm init` or `npm init -y`
+
+This will make `package.json` which is:
+
+- A manifest file of dependencies
+- Project settings
+- Project meta-data
+- A way to run scripts _with_ package.json settings
+
+## Alternatives
+
+- yarn
+- pnpm
+- bun
+
+## Dependencies
+
+Topics:
+
+- Installing deps with `npm install <package>` or `npm i <package>`
+- "dependencies" vs "devDependencies": `npm i -D <package>`
+- Package-lock
+- SEMVER: 1.2.3 (Major.Minor.Patch)
+- Semver ranges: ^ (for minor) and ~ (for patch)
+  - `^1.0.0` in package.json means we're eligible to be using `1.1.0` in package-lock
+- Installing specific versions: `npm install package@1.0`
+- Uninstalling via `npm uninstall <package>`
+
+# Using an existing project
+
+If you've just cloned an existing project, it will have `package.json` and `package-lock.json` already since these are committed in git. You won't have a `node_modules` folder though since we don't typically commit those to git (since they're big).
+
+Run `npm install` without adding a package name and it will seek through all the packages listed in `package.json` and it will make your `node_modules` folder.
+
+# Common Commands
+
+```sh
+# Docs for `npm install`
+# https://docs.npmjs.com/cli/v6/commands/npm-install
+
+# This command will install all dev and production dependencies found in
+# package.json. It's typically used when you've just cloned a repo. The
+# repo will come with a #package.json but not a node_modules folder, so
+# this command will install all files in node_modules:
+npm install
+
+# Alias for `npm install`
+npm i
+
+# Install a specific package into node_modules. It also adds the package
+# to the dependencies property of package.json:
+npm i <package-name>
+
+# Same as above but adds to devDependencies section of package.json. You
+# can also use `--save-dev`
+npm i <package-name> -D
+
+# Install a package globally (outside of your project in npm's global
+# folder on your machine). This is typically used when the package is
+# going to add a binary for you to use in CLI.
+npm i -g <package-name>
+
+# For example
+npm i -g http-server
+
+# Now you can navigate to any path on your computer and run this command
+http-server
+
+# http-server will run the local path as a web server, using the files
+# as static assets.
+
+# List NPM modules installed in the current path's node_modules folder
+npm list --depth=0
+
+# List  NPM modules installed globally on machine
+npm list -g --depth=0
+```
+
+## Scripts
+
+Topics:
+
+- Show the basics of scripts: Run a node file via `"start": "node index.js"`
+- Show `npm run <script>` vs defaults like `npm start`
+- Binaries: `npm install http-server` and show how we can't just do `$ http-server`
+  but rather we have to made a script so NPM can run the correct binary in NODE_MODULES
+
+## Installing Globally
+
+Topics:
+
+- `npm install -g <package>` vs `npx <package>`
+- Show `http-server` for example
+
+## Maintenance
+
+Fixes dependencies and transitive dependencies when they need to be updated from a security standpoint. You will be notified via CLI when you need to run this
+
+- `npm audit`: List them
+- `npm audit fix`: Fix them
+
+## package.json
+
+- Explain `engines`
+  If we `npm i` something that's not compatible with engines, we'll get a warning
+
+```json
+{
+  // The name of your project (must be lowercase and one word, or hyphenated)
+  "name": "my-project",
+
+  // The version of your project (follow semantic versioning: MAJOR.MINOR.PATCH)
+  "version": "1.0.0",
+
+  // A brief description of your project
+  "description": "A brief description of my awesome project",
+
+  // The entry point file of your project (commonly "index.js")
+  "main": "index.js",
+
+  // Keywords to help others find your project (an array of strings)
+  "keywords": ["example", "project", "node"],
+
+  // The author of the project (your name and email)
+  "author": "Your Name <your.email@example.com>",
+
+  // The license under which your project is released
+  "license": "MIT",
+
+  // Scripts to automate tasks (run with `npm run <script-name>`)
+  "scripts": {
+    "start": "node index.js",
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+
+  // Dependencies required for your project to run
+  "dependencies": {
+    "express": "^4.17.1"
+  },
+
+  // Development dependencies for your project (only needed during development)
+  "devDependencies": {
+    "nodemon": "^2.0.12",
+    "eslint": "^7.32.0"
+  },
+
+  // Peer dependencies (specify compatible versions of packages your project works with)
+  "peerDependencies": {
+    "react": "^17.0.2"
+  },
+
+  // Engines field to specify versions of Node.js and npm your project is compatible with
+  "engines": {
+    "node": ">=14.0.0",
+    "npm": ">=6.0.0"
+  },
+
+  // Repository information (useful if your project is hosted on a platform like GitHub)
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/yourusername/my-awesome-project.git"
+  },
+
+  // Bugs field to specify where issues and bugs should be reported
+  "bugs": {
+    "url": "https://github.com/yourusername/my-awesome-project/issues"
+  },
+
+  // Homepage of the project (usually a website or GitHub repository)
+  "homepage": "https://github.com/yourusername/my-awesome-project#readme"
+}
+```

Diff for: examples/02-npm-basics/package.json

@@ -0,0 +1,11 @@
+{
+  "name": "npm-basics",
+  "version": "1.0.0",
+  "main": "index.js",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "author": "",
+  "license": "ISC",
+  "description": ""
+}

Diff for: examples/03-module-basics/NOTES.md

@@ -0,0 +1,24 @@
+# Module Basics
+
+- CommonJS vs ESM (EcmaScript Modules)
+- "EcmaScript" === the official name of JavaScript
+- Default vs Named import/exports
+
+MDN: The official docs for HTML, CSS, and JS
+
+https://developer.mozilla.org/en-US/docs/web/javascript/reference/statements/export
+https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import
+
+## package.json
+
+```json
+{
+  // Default. We don't need to add
+  "type": "commonjs",
+
+  // Needed if we want to use ESM
+  "type": "module"
+}
+```
+
+Sometimes we don't need to designate `type: module` if we're not running Node directly but rather a bundler like Webpack is running and understands ESM

Diff for: examples/03-module-basics/index.js

@@ -0,0 +1,3 @@
+const sayHi = require('./utils')
+
+sayHi()

Diff for: examples/03-module-basics/package.json

@@ -0,0 +1,7 @@
+{
+  "name": "module-basics",
+  "// type": "commonjs",
+  "scripts": {
+    "start": "node index.js"
+  }
+}

Diff for: examples/03-module-basics/utils.js

@@ -0,0 +1,5 @@
+function sayHi() {
+  console.log("Hello CommonJS (Node's original module resolver)")
+}
+
+module.exports = sayHi

Diff for: examples/04-browser-modules/app/index.html

@@ -0,0 +1,21 @@
+<!DOCTYPE html>
+<html lang="en">
+
+<head>
+  <meta charset="UTF-8">
+  <title>Example</title>
+</head>
+
+<body>
+  <h1>Browser Modules</h1>
+  <p>
+    Check the JavaScript console in the browser.
+  </p>
+  <p>
+    Also, see the MDN docs on <a target="_blank"
+      href="https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script#browser_compatibility">script tags</a>
+  </p>
+  <script type="module" src="index.js"></script>
+</body>
+
+</html>

Diff for: examples/04-browser-modules/app/index.js

@@ -0,0 +1,3 @@
+import { sayHi } from './utils.js'
+
+sayHi()

Diff for: examples/04-browser-modules/app/utils.js

@@ -0,0 +1,3 @@
+export function sayHi() {
+  console.log("Let's bundle this code")
+}

Diff for: examples/04-browser-modules/package-lock.json

@@ -0,0 +1,10 @@
+{
+  "name": "browser-modules",
+  "type": "module",
+  "scripts": {
+    "start": "http-server app -p 3000"
+  },
+  "devDependencies": {
+    "http-server": "^14.1.1"
+  }
+}

Diff for: examples/04-browser-modules/package.json

@@ -0,0 +1,2 @@
+- Show basic bundling with ESBuild
+- We'll do minified bundling next for the browser

Diff for: examples/05-bundling/NOTES.md

@@ -0,0 +1,3 @@
+import { sayHi } from './utils.js'
+
+sayHi()

Diff for: examples/05-bundling/app/index.js

@@ -0,0 +1,3 @@
+export function sayHi() {
+  console.log("Let's bundle this code")
+}

Diff for: examples/05-bundling/app/utils.js

@@ -0,0 +1,10 @@
+{
+  "name": "bundling",
+  "type": "module",
+  "scripts": {
+    "build": "esbuild app/index.js --bundle --outfile=build/build.js"
+  },
+  "devDependencies": {
+    "esbuild": "0.21.4"
+  }
+}

Diff for: examples/05-bundling/package-lock.json

@@ -0,0 +1,15 @@
+<!DOCTYPE html>
+<html lang="en">
+
+<head>
+  <meta charset="UTF-8">
+  <title>Example</title>
+</head>
+
+<body>
+  <h1>Bundle for the Browser</h1>
+  <p>Check the JavaScript console in the browser</p>
+  <script src="build.js"></script>
+</body>
+
+</html>

Diff for: examples/05-bundling/package.json

@@ -0,0 +1,3 @@
+import { sayHi } from './utils.js'
+
+sayHi()

Diff for: examples/06-bundle-for-browser/app/index.html

@@ -0,0 +1,3 @@
+export function sayHi() {
+  console.log("Let's bundle this code")
+}

Diff for: examples/06-bundle-for-browser/app/index.js

@@ -0,0 +1,18 @@
+{
+  "name": "bundling-for-browser",
+  "type": "module",
+  "scripts": {
+    "// Can't run two things in parallel": "",
+    "dev-bad": "npm run dev:build && npm run dev:server",
+    "dev:build": "node scripts/run-build.js",
+    "dev:server": "http-server build -p 3000",
+    "// Explain run-p, aka npm-run-all --parallel": "",
+    "dev": "run-p dev:*"
+  },
+  "devDependencies": {
+    "chokidar": "^3.6.0",
+    "esbuild": "0.21.4",
+    "http-server": "^14.1.1",
+    "npm-run-all": "^4.1.5"
+  }
+}

Diff for: examples/06-bundle-for-browser/app/utils.js

@@ -0,0 +1,23 @@
+import { promises as fsPromises } from 'fs' // the esm version
+import * as esbuild from 'esbuild'
+import { watch } from 'chokidar'
+
+async function build() {
+  await esbuild.build({
+    entryPoints: ['app/index.js'],
+    bundle: true,
+    outfile: 'build/build.js',
+    minify: true,
+    sourcemap: true,
+  })
+
+  await fsPromises.copyFile('app/index.html', 'build/index.html')
+}
+build()
+
+const watcher = watch(['app/**/*'])
+console.log('Watching app')
+watcher.on('change', () => {
+  console.log('Rebuilding...')
+  build()
+})

Diff for: examples/06-bundle-for-browser/package-lock.json

@@ -0,0 +1,14 @@
+<!DOCTYPE html>
+<html lang="en">
+
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>JavaScript</title>
+</head>
+
+<body>
+  Hello
+</body>
+
+</html>

Diff for: examples/06-bundle-for-browser/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "javascript-node-workshop",
+  "private": true,
+  "scripts": {
+    "/////////// LECTURES:": "",
+    "lecture-1": "cd lessons/01-javascript/lecture && http-server -p 3000"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.3.0",
+    "eslint": "^9.3.0",
+    "globals": "^15.3.0",
+    "http-server": "^14.1.1"
+  },
+  "prettier": {
+    "printWidth": 100,
+    "semi": false,
+    "singleQuote": true,
+    "tabWidth": 2
+  }
+}