Dev setup

Tools

The following global tools are recommended to simplify development:

• NVM - lets you manage multiple versions of Node on one machine (the version this project currently uses is in .nvmrc).
• direnv - lets you manage environment variables (and the active version of Node) based on the .envrc of the directory you're in.

Installation

1. Go to https://github.com/textbook/starter-kit/generate (or click "Use this template") to create your own version of this repository

2. Clone the new repository to your local machine.

3. cd into the repository's directory on your local machine. You can run git status to check you're in the right place, it should say something like

   On branch master
   Your branch is up to date with 'origin/master'.
   
   nothing to commit, working tree clean
   

   • If you have direnv installed, you may see

     direnv: error .envrc is blocked. Run `direnv allow` to approve its content.
     

     If you trust the repo, you can run direnv allow as suggested.

4. Install the dependencies by running npm install; this will create a node_modules/ directory and fill it with the requirements specified in package.json and package-lock.json.

5. Run the app using either npm run dev (developer mode, with watching/reloading of your code as you make changes) or npm run serve (production mode, to check what will actually get deployed).

Note that npm [run] start is designed for production use (in e.g. Heroku), so will likely not do what you expect if you run it locally; it may run older code, or you may see an error like:

$ npm start

> starter-kit@0.0.1 start /path/to/starter-kit
> node dist/server.js

internal/modules/cjs/loader.js:797
    throw err;
    ^

Error: Cannot find module '/path/to/starter-kit/dist/server.js'
    at Function.Module._resolveFilename (internal/modules/cjs/loader.js:794:15)
    at Function.Module._load (internal/modules/cjs/loader.js:687:27)
    at Function.Module.runMain (internal/modules/cjs/loader.js:1025:10)
    at internal/main/run_main_module.js:17:11 {
  code: 'MODULE_NOT_FOUND',
  requireStack: []
}
npm ERR! code ELIFECYCLE
npm ERR! errno 1
npm ERR! starter-kit@0.0.1 start: `node dist/server.js`
npm ERR! Exit status 1
npm ERR! 
npm ERR! Failed at the starter-kit@0.0.1 start script.
npm ERR! This is probably not a problem with npm. There is likely additional logging output above.

npm ERR! A complete log of this run can be found in:
npm ERR!     /path/to/.npm/_logs/2019-12-27T17_38_04_214Z-debug.log

If you try to directly run the raw source code instead, e.g. node server/server.js, you'll get a syntax error on the use of ES6 modules:

$ node server/server.js
(node:53797) Warning: To load an ES module, set "type": "module" in the package.json or use the .mjs extension.
/Users/jsharpe/workspace/starter-kit/server/server.js:1
import http from "http";
^^^^^^

SyntaxError: Cannot use import statement outside a module
    at wrapSafe (internal/modules/cjs/loader.js:1053:16)
    at Module._compile (internal/modules/cjs/loader.js:1101:27)
    at Object.Module._extensions..js (internal/modules/cjs/loader.js:1157:10)
    at Module.load (internal/modules/cjs/loader.js:985:32)
    at Function.Module._load (internal/modules/cjs/loader.js:878:14)
    at Function.executeUserEntryPoint [as runMain] (internal/modules/run_main.js:71:12)
    at internal/main/run_main_module.js:17:47

The code needs to be built before being started - that happens automatically in e.g. Heroku, and is what npm run serve does for you (see Architecture).

Ports

If you see EADDRINUSE when trying to run dev or serve, you may have other processes running on your machine that are using ports the starter kit expects. You can check which processes these are using the command:

lsof -i :<port>

If you see existing npm commands running, you may have terminals running in the background somewhere - find them and stop them! If you see some other program running, you may need to switch ports. You can do this as follows:

• npm run dev:
  • Frontend (default: 3000): you need to change the line port: 3000, in client/webpack/dev.config.js
  • Backend (default: 3100): you need to change this in two places, the line "/api": "http://localhost:3100", in client/webpack/dev.config.js and the line "dev:serve": "wait-on -l file:dist/server.js && cross-env PORT=3100 nodemon dist/server.js --watch dist", in package.json.
• npm run serve:
  • Backend (default: 3000): the easiest way to override this is when you actually run the server, so you can do e.g. PORT=3210 npm run serve. Alternatively you can change the line const port = parseInt(process.env.PORT || "3000"); in server/server.js.