TWELVE HEROES 
=============
*The digital version of the boardgame*
--------------------------------------

- [TWELVE HEROES](#twelve-heroes)
  - [*The digital version of the boardgame*](#the-digital-version-of-the-boardgame)
  - [**How to modify & run**](#how-to-modify--run)
    - [1. requirements](#1-requirements)
    - [2. Clone the repo](#2-clone-the-repo)
    - [3. Work in your branch](#3-work-in-your-branch)
    - [4. To run the app for tests](#4-to-run-the-app-for-tests)
  - [**Some info about the project**](#some-info-about-the-project)
    - [1. npm stuff](#1-npm-stuff)
    - [2. Editor config & VS code settings](#2-editor-config--vs-code-settings)
    - [3. ES lint](#3-es-lint)
    - [4. Babel](#4-babel)
    - [5. Cordova](#5-cordova)
    - [6. Webpack](#6-webpack)
    - [7. Git ignore](#7-git-ignore)
    - [8. Source code](#8-source-code)
  - [**NPM scripts**](#npm-scripts)
    - [1. How NPM scripts work](#1-how-npm-scripts-work)
    - [2. Description of the project npm scripts](#2-description-of-the-project-npm-scripts)
  - [**Useful links**](#useful-links)
    - [1. Google drive stuff](#1-google-drive-stuff)
    - [2. Trello](#2-trello)



## **How to modify & run**

### 1. requirements
   * NodeJS : >= v10.17.0
   * npm : >= v6.11.3

### 2. Clone the repo
   * clone with your username (It will ask for your bitbucket password):  
      `git clone https://USERNAME@bitbucket.org/jojolb/twelve-heroes.git`

### 3. Work in your branch
   * `cd twelve-heroes`

   * Create your own branch from this code and name it as you want :  
    `git checkout -b \<name of your branch\> master`

   * To push modifs :  
    from project root folder ("twelve-heroes/") :
       1) `git add .` ( <-- with '.', it will add all modified files for a commit)
       2) `git commit -m "description of the change"`
       3) `git push origin \<name of your branch\>`
  
### 4. To run the app for tests
   * go in project root folder ("twelve-heroes/")
   * do **once** : `npm install` (<-- this will install all dependencies, might take some time)
   * do : `npm run start`  
    Wait.... It will run the server (socket.io stuff) and launch app in chrome  
    ( or do : `npm run dev` to launch app in chrome only without server)



## **Some info about the project**

### 1. npm stuff
   * file *package.json* contains project config for npm
   * File *package-lock.json* is generated by npm. It never needs to be changed manually
   * Directory *node_modules* contains all dependant libraries. It is not on git, it is only locally
   * npm is usefull to keep track of dependencies and install them rapidly.
   * it provides npm scripts (see [**below**](#npm-scripts)). These are shortcuts for building, testing, deploying

### 2. Editor config & VS code settings
   * File *.editorconfig* contains config for editing
   * Install on VS code the plugin "EditorConfig for Visual Studio Code"
   * It will ensure we have same code format
   * With VS code, select code and select "Format Selection"
   * File *settings.json* contains config for VS code editor (overrides global config)

### 3. ES lint
   * File *.eslintrc.json* contains Linter configuration
   * It defines common coding rules
   * It acts like a "compiler", it will throw warnings or errors if coding rules were not respected

### 4. Babel
   * File *.babelrc* contains Babel config
   * Here we can use Javascript ES6 to code (new keywords like 'class')
   * Babel takes care of "transpiling" this ES6 code to ES5
   * Most browsers are compatible ES5 and not ES6, this is why it is necessary

### 5. Cordova
   * File *config.xml* contains Cordova config
   * Cordova is a framework that will package our app for Apple or Android
   * Directory "*plugins*" and "*platforms*" are not in git. They are used by Cordova when used to run the project.

### 6. Webpack
   * File *webpack.config.js* contains webpack config
   * Webpack is a powerful tool that lightens the code and bundles it intelligently. It is kind of a "compiler"
   * It also allows to run a local server to test our JS code (using BrowserSync plugin)
   * It supports "Hot reloading", meaning that once app is running, you can modify the code and it will reloads live in the browser
   * Directory "*www*" is where webpack is going to put the "compiled" app

### 7. Git ignore
   * File *.gitignore* is used for git
   * It defines the files we don't want to version on git (like build files, binaries, external node libraries) 

### 8. Source code
   * "*src*" contains app code (client code)
   * "*server*" contains server code



## **NPM scripts**
"scripts": {

    "server": "babel-node server/main.js",
    "dev": "webpack --watch",
    "precor-build": "cordova prepare",
    "cor-build": "CORDOVA=true cordova build -- --webpackConfig webpack.config.js",
    "cordova": "CORDOVA=true cordova run -- -w webpack.config.js",
    "start": "npm-run-all --parallel server dev lint:watch",
    "lint": "esw webpack.config.* src --color",
    "lint:watch": "npm run lint -- --watch",
    "ngrok": "ngrok http 3000",
    "share": "npm-run-all --parallel server dev ngrok",
    "test": "mocha --reporter progress \"src/**/*.test.js\"",
    "test:watch": "npm run test -- --watch",
    "clean": "git clean -fdx -e node_modules"
  }

### 1. How NPM scripts work
   * In *package.json*, in section *"scripts"* are defined the npm scripts
   * `npm run <script name>` will run *\<script name\>*
   * `npm start` is a shortcut for `npm run start`
   * *pre* and *post* keywords :
     * Using **pre**script-name and **post**script-name
     * with `npm run script-name` it will first run **pre**script-name, then script-name, and finally **post**script-name
   * Using **npm-run-all**, it will run at the same time all the scripts declared behind this keyword
     * Useful for example to run clients and server at the same time, along with the "linting"

### 2. Description of the project npm scripts
   * `npm run server`
     * It launches the server (listening for clients connections using sockets)
   * `npm run dev`
     * It is launching the app for dev (not using cordova)
   * `npm run cor-build`
     * It builds the code and prepares it for Cordova
     * It will run precor-build automatically
   * `npm run cordova`
     * It runs the app using Cordova
     * Today the only target is "browser" (no Apple or Android yet)
   * **`npm run start` or `npm start`**
     * It runs in parallel the server, the app and the linting
     * While it is running you can modify app code and save
       * The linter will show live new errors or warnings, if any
       * Refresh page on chrome to see the changes
   * `npm run lint`
     * It checks the code once, see [above]((#3-es-lint))
   * `npm run lint:watch`
     * It checks the code, see [above]((#3-es-lint))
     * In addition to the command above, it checks live again the code after save
   * `npm run ngrok`
     * It allows to share temporarily the app on public network
     * After running `npm start` or `npm run dev`
     * Run this and it will give a public http address
     * If other person goes to this http address it will access the app
     * Useful to share briefly to the other what we are doing
     * **Use *run share* below instead**
   * `npm run share`
     * It runs in parallel the dev, server and tunnel (ngrok)
     * ngrok will provide an http address which can be used to access the app from public network
   * `npm run test`
     * It runs *once* all the tests : all files *.test.js
     * Says what passed or failed
   * `npm run test:watch`
     * It runs the tests like above, after modifs to code and save, it will re-run automatically the tests
   * `npm run clean`
     * It cleans the build directory
     * **WARNING : It will also remove new files or directory created and not added yet into git**

## **Useful links**

### 1. Google drive stuff
https://drive.google.com/open?id=11j-IW2OL5ZOaeF3YGyvXjFDLz7BJdpW_

### 2. Trello
https://trello.com/b/FZXHfg2J/twelve-heroes