Developers

• Developers
  • Pre-requisites
  • Development Tips
    • Use nvm to manage the npm versions
    • Tips for the VisualStudio Code IDE
    • Tips for Windows developers
  • Npm Scripts
    • Some comments about selected package.json scripts
  • Debugging the examples
    • Develop with modified ud-viz library in your demo
  • Continuous Integration (Travis CI)
  • Contributing
  • Publishing
  • Generating the documentation

Pre-requisites

Developing UD-Viz applications requires some knowledge about :

• git (repository, branches, fork): refer e.g. to this git gateway
• the JavaScript programming language: refer e.g. to MDN docs
• node.js: refer e.g. to W3School tutorial
• npm
• three.js library
• iTowns
• the UD-Viz framework.

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, you can install the following extentions to make your life easier:

• eslint - allows you e.g. to automatically fix the coding style e.g. when saving a file.
• Prettier ESLint - JS, JSON, CSS, and HTML formatter.
• Mintlify - 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 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 file defines a set of scripts whose respective purpose are quickly documented here

Some comments about selected package.json scripts

Consider the dev-examples script

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, process.env.
• nodemon [--options] ./bin/devExamples.js: 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) when one those files changes (e.g. was edited).

We can now dive into bin/devExamples.js where

• exec and spawn are two functions from child-process-promise which allows to execute node script. See Promise doc.
• 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.
• const child = spawn('cross-env NODE_ENV=development node', ['./bin/backEnd.js'], { shell: true, });: Interprets bin/backEnd.js that launches an express server.

Debugging the examples

npm run dev-examples

• Run a watched routine devExamples.js with nodemon.

Develop with modified ud-viz library in your demo

When developing an application that uses 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

  "dependencies": {
     "@ud-viz/*": "x.x.x"
  }
  

  should replaced with

  "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

  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:

  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.

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) which check packages dependencies vulnerabilities.
• npm run test-links: Run this script which check if links are not broken.
• node ./test/docs.js: Run this script 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

Publishing

For creating a new release see ReleasePublish.md

Generating the documentation

The Online documentation can be re-generated by following these instructions.