# Developers - [Developers](#developers) - [Pre-requisites](#pre-requisites) - [Development Tips](#development-tips) - [Use nvm to manage the npm versions](#use-nvm-to-manage-the-npm-versions) - [Tips for the VisualStudio Code IDE](#tips-for-the-visualstudio-code-ide) - [Tips for Windows developers](#tips-for-windows-developers) - [Npm Scripts](#npm-scripts) - [Some comments about selected `package.json` scripts](#some-comments-about-selected-packagejson-scripts) - [Debugging the examples](#debugging-the-examples) - [Develop with modified ud-viz library in your demo](#develop-with-modified-ud-viz-library-in-your-demo) - [Continuous Integration (Travis CI)](#continuous-integration-travis-ci) - [Contributing](#contributing) - [Publishing](#publishing) - [Generating the documentation](#generating-the-documentation) ## Pre-requisites Developing UD-Viz applications requires some knowledge about : - `git` (repository, branches, fork): refer e.g. to [this git gateway](https://github.com/VCityTeam/UD-SV/blob/master/Tools/ToolGit.md) - the [JavaScript](https://developer.mozilla.org/en-US/docs/Web/javascript) programming language: refer e.g. to [MDN docs](https://developer.mozilla.org/en-US/docs/Learn/Getting_started_with_the_web/JavaScript_basics) - [node.js](https://en.wikipedia.org/wiki/Node.js): refer e.g. to [W3School tutorial](https://www.w3schools.com/nodejs/nodejs_get_started.asp) - [npm](https://en.wikipedia.org/wiki/Npm_(software)) - [three.js](https://threejs.org/) library - [iTowns](http://www.itowns-project.org) - [the UD-Viz framework](https://github.com/VCityTeam/UD-Viz). ## Development Tips ### Use nvm to manage the npm versions Developers are advised to use node version manager (nvm). nvm allows you to quickly install and use different versions of node via the command line. To download and install follow this link: https://github.com/nvm-sh/nvm#installing-and-updating ### Tips for the VisualStudio Code IDE When using [Visual Studio Code](https://code.visualstudio.com/), you can install the following extentions to make your life easier: - [eslint](https://www.digitalocean.com/community/tutorials/linting-and-formatting-with-eslint-in-vs-code) - allows you e.g. to automatically fix the coding style e.g. [when saving a file](https://www.digitalocean.com/community/tutorials/linting-and-formatting-with-eslint-in-vs-code). - [Prettier ESLint](https://marketplace.visualstudio.com/items?itemName=rvest.vs-code-prettier-eslint) - JS, JSON, CSS, and HTML formatter. - [Mintlify](https://marketplace.visualstudio.com/items?itemName=mintlify.document) - AI-powered documentation generator. (may require rewriting by a human) ### Tips for Windows developers As configured, the coding style requires a Linux style newline characters which might be overwritten in Windows environments (both by `git` and/or your editor) to become `CRLF`. When such changes happen eslint will warn about "incorrect" newline characters (which can always be fixed with `npm run eslint-fix` but this process quickly gets painful). In order to avoid such difficulties, the [recommended pratice](https://stackoverflow.com/questions/1967370/git-replacing-lf-with-crlf) consists in 1. setting git's `core.autocrlf` to `false` (e.g. with `git config --global core.autocrlf false`) 2. configure your editor/IDE to use Unix-style endings 3. In order to use scripts that launch a shell script with Powershell: `npm config set script-shell "C:\\Program Files\\git\\bin\\bash.exe"` ## Npm Scripts The npm [`package.json`](../../package.json) file defines a set of scripts whose respective purpose are quickly documented here | Script | Description | | ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `npm run clean` | Remove files and folders generated by `npm install` and the `npm run build-(dev-)examples` script such as `./node_modules`, `package-lock.json`, and `./dist` | | `npm run clear-node` | ***Linux Command***: Kill all node process (this is a sudo script) | | `npm run reset` | Reinstalls npm dependencies. This script runs `npm run clean` and `npm install` command | | `npm run build-examples` | Build a production bundle base on this [webpack config](../../webpack.config.js) | | `npm run build-dev-examples` | Build a development bundle base on this [webpack config](../../webpack.config.js) | | `npm run dev-examples` | Launch a watcher running this [script](../../bin/devExamples.js). See [here](#debugging-the-examples) for more information | | `npm run eslint` | Run the linter. See [here](./Contributing.md#coding-style-linter) for more information | | `npm run eslint-quiet` | Run the linter without displaying warnings, only errors | | `npm run eslint-fix` | Run the linter and attempt to fix errors and warning automatically | | `npm run test-unit` | Build examples bundle if needed and run `npm run test` in each packages . Also ran by CI. See [here](#continuous-integration-travis-ci) for more information | | `npm run test-functional` | Build examples bundle if needed and run each *.html in ./examples folder . Also ran by CI. See [here](#continuous-integration-travis-ci) for more information | | `npm run test-links` | Run this [script](../../test//links.js) to detect dead links in markdown. Also ran by CI. See [here](#continuous-integration-travis-ci) for more information | | `npm run local-ci` | Run CI on your local computer. See [here](#continuous-integration-travis-ci) for more information | | `npm run pre-publish` | Change version in all package.json ( eg `npm run pre-publish x.x.x` ). See [this script](../../bin/prePublish.js) | | `npm run docs` | Delete old docs and run this [script](../../bin/generateJsDoc.js) which generate docs | | `npm run dev-docs` | Launch a watcher for generating and debugging the documentation. See [here](../../Readme.md) for more information | | `npm run back-end` | run an http server (with some [string-replace](https://www.npmjs.com/package/string-replace-middleware)) + a game socket service.
http://locahost:8000/ | | `npm run analyze-bundle` | Use [webpack-bundle-analyzer](https://www.npmjs.com/package/webpack-bundle-analyzer) to see what's inside the examples bundle | | `npm run analyze-dev-bundle` | Use [webpack-bundle-analyzer](https://www.npmjs.com/package/webpack-bundle-analyzer) to see what's inside the examples dev bundle | | `npm run start` | Run `npm run build-examples` and `npm run back-end` | ### Some comments about selected `package.json` scripts Consider the `dev-examples` script ```bash cross-env NODE_ENV=development nodemon --signal SIGKILL --trace-warnings --verbose [--watch ./packages/PACKAGE_NAME] --delay 2500ms ./bin/devExamples.js -e js,css ``` This script builds on - **`cross-env NODE_ENV=development`**: *cross-env* package will allows to add variable in command line (*here NODE_ENV*) to *process.env*. See [cross-env](https://www.npmjs.com/package/cross-env), [process.env](https://nodejs.org/dist/latest-v8.x/docs/api/process.html#process_process_env). - **`nodemon [--options] ./bin/devExamples.js`**: [nodemon](https://www.npmjs.com/package/nodemon) is a node provided development oriented tool. Its purpose is to automatically restart the interpretation of a set of javascript files (*here [bin/devExamples.js](../../bin/devExamples.js)*) when one those files changes (e.g. was edited). We can now **dive into [bin/devExamples.js](../../bin/devExamples.js)** where - exec and spawn are two functions from [*child-process-promise*](https://www.npmjs.com/package/child-process-promise) which allows to execute node script. See [Promise doc](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise). - **`exec('npm run build-dev-examples')`**: - **`cross-env NODE_ENV=development webpack --config=./webpack.config.js`**: webpack is the tool it permits to create a bundle of your code. The config is defined in *./webpack.config.json*. See doc [here](https://webpack.js.org/concepts/). - **`const child = spawn('cross-env NODE_ENV=development node', ['./bin/backEnd.js'], { shell: true, });`**: Interprets [bin/backEnd.js](../../bin/backEnd.js) that launches an [express](https://www.npmjs.com/package/express) server. ## Debugging the examples ```bash npm run dev-examples ``` - Run a watched routine [devExamples.js](../../bin/devExamples.js) with [nodemon](https://www.npmjs.com/package/nodemon). ### Develop with modified ud-viz library in your demo When developing an application that uses [UD-Viz](https://github.com/VCityTeam/UD-Viz) as library, you might need to propose modifications/fixes/improvements of UD-Viz. In doing so you will need a set up that allows for simultaneously modifying both codes (the one of your application and the one of UD-Viz) in order to co-evolve UD-Viz and its usage within your application. In order to establish that specific developing context you might - clone both repositories side by side (that is your cloned application repository stands in the same directory as the cloned UD-Viz) on your local - within the cloned UD-Viz repository, run `npm install` (because your `webpack.config.js` will make reference to `../UD-Viz/node_modules`). - Modify your the `package.json` of your application in order to "point" to the cloned version of the UD-Viz library. Entries of the form ```json "dependencies": { "@ud-viz/*": "x.x.x" } ``` should replaced with ```json "dependencies": { "@ud-viz/*": "file:../UD-Viz/packages/*" } ``` where the path is a relative path from the `package.json` to your cloned version of the UD-Viz library. Notice that you should only modify the paths to the UD-Viz npm (sub-)packages that you wish to adapt. - Reinstall ud-viz npm packages ```bash rm -f -r node_modules && rm -f package-lock.json && npm i ``` - Eventually you have to modify the `webpack.config.js` in order to indicate to webpack what directories should be searched when resolving modules the UD-Viz's 'node_modules' folder: ```js module.exports = { //... resolve: { modules: ['../UD-Viz/node_modules', './node_modules'], }, }; ``` It is important to add the '../UD-Viz/node_modules' in first position of the array. When you application uses code watchers (e.g. nodemon) on automatic rebuild purposes, the code watchers will be blind to changes operated in the ../UD-Viz/ file hierarchy. ## Continuous Integration (Travis CI) Each time origin/master branch is impacted by changes, Travis CI is triggered. It does a set of jobs describe in [travis.yml](../../.travis.yml). Jobs list : - `npm run eslint`: Lint code sources - `npm run test-unit`: Unit test - `npm run test-functional`: Functional test - `npm audit --audit-level=low`: Npm native command ([npm-audit](https://docs.npmjs.com/cli/v6/commands/npm-audit)) which check packages dependencies vulnerabilities. - `npm run test-links`: Run this [script](../../test/links.js) which check if links are not broken. - `node ./test/docs.js`: Run this [script](../../test/docs.js) which check if documentation is generated without warning or error. ## Contributing For information on the accepted coding style, submitting Issues, and submitting Pull Requests see [Contributing.md](./Contributing.md) ## Publishing For creating a new release see [ReleasePublish.md](./ReleasePublish.md) ## Generating the documentation The [Online documentation](https://vcityteam.github.io/UD-Viz/html/index.html) can be re-generated by [following these instructions](../../Readme.md).