Naming Conventions / Directory Layout

build/         # compiled and concatenanted classes
dist/         # compiled JS classes
src/         #  ES6 and Handlebars templates
style/main.scss         # which imports other SASS and/or CSS files
resource/    # Copied as is to build directory
lib-export.js    # the entrypoint ala index.js

Build Pipeline

  • All web dependencies are downloaded and concatenated into build/dependencies.jsand build/dependencies.css
  • ES6 files are compiled and concatenanted into build/app.jswhere 'app.js' is the mainFilein package.json(inferred from package's name by default)
  • CSS/LESS/SASS are compliled and concatened into build/app.css
  • In production mode all source is minified and source maps generated.

Handlebars Templates

A Handlebar template is any file ending in .hbsit is available in the TEMPLATESglobal without the extension.
A Handlebar partial is any file begining with _and ending in .hbsand is automatically registered

Build steps:

  • export your NPM_TOKEN
  • Run npm install -g "yarn@^1.5.1"
  • Run yarn setupto install and build all required dependencies

Dev lifecycle commands:

  • Run yarn setupto install dependencies of client project if its package.json is updated upstream
  • Run yarn add my-packageto add a dependency to build-tools
  • Run yarn add --dev my-packageto add a build-time dependency to client project if needed
  • Run yarn add my-packageto add a web dependency to client project if needed. Note that EgisUI's dependencies are included everywhere.
  • Run yarn upgrade my-packageto upgrade a dependency in build-tools or client project.
  • Run yarn devto build files suitable for wathcing and startup a watch server
  • Run yarn buildto build a package suitable for production
  • Run yarn testto run karma test suites

Customizing builds using dependencies.json and package.json


All package.json dependencies are considered web dependencies. Their main files are concatenanted together in package name order. The deps' files that get concatenated can be overriden in dependencies.json as follows:

"overrides": {
        "perfect-scrollbar": {
          "main": [

To exclude certain large libraries from concatenantion list in exclude, the main files will be concated together and placed in build/<libray name>

"standalone": ["handsontable", "codemirror"]

To exclude libraries that have already been packaged elsewhere:

"excludes": ["jquery"]

To copy entire directories from dependencies:

"directories": {
    "fontawesome": "fonts/*",
    "bootstrap": "fonts/*"

To create a plugin package:

"plugin": "PortalApp",

This will create a .zip instead of a .war and place all the compiled .js file in to a subdirectory System/plugins/{plugin}


For frontend development env our browsersync integration may be helpful. It:

  • injects CSS changes immediately
  • auto-reloads page in browsers if JS files are changed - including your mobile device's browser
  • supports running multiple modules in dev mode in parallel

In each build-toolsproject:

yarn dev

And then after 1 or more yarn devservers are running:

yarn browsersync

If your files are being served from anything other then localhoste.g.

cd /path/to/EgisUI
yarn dev

# in another terminal window/tab
cd /path/to/build-tools
yarn browsersync --proxied-host=

This also allows to run a library (EgisUI, eSign, etc) or Portal plugin locally in dev mode in context of remote host, e.g. UAT:

cd /path/to/MyPlugin
yarn dev

# in another terminal window/tab
cd /path/to/build-tools
yarn browsersync --proxied-host=sandbox.some.com --proxied-port=80 --plugin=MyPlugin

Note the --pluginparameter above - you need to specify it by its directory name to make browsersync handle it. This is because we only want one plugin to work at any given time.

For SSL mode, just specify https protocol:

yarn browsersync -- --proxied-host=https://testbox.papertrail.co.za

In case you also want dev mode of EgisUI and a plugin while proxying an https UAT and access it from another machine you can do it following way:

# open terminal tab
cd [egis-ui-path]
yarn dev --serve=false --scheme=https --host=[your-ip]

# open another terminal tab
yarn browser-sync start --server --https --files "dist/**/*" --port 8101 --cors

# open another terminal tab
cd [plugin-path]
yarn dev --serve=false --scheme=https --host=[your-ip]

# open another terminal tab
yarn browser-sync start --server --https --files "dist/**/*" --port 8120 --cors

# open another terminal tab
cd [build-tools-path]
yarn browsersync --proxied-host=https://bidshows-dev.papertrail.co.za --plugin=[your-plugin-name]


  • URLs with default pages other than index.html, e.g. http://papertrail.lvh.me:3001/web/eSign/?3760don't work, so you'll get "page not found" if you try to use Sign action. Specify http://papertrail.lvh.me:3001/web/eSign/sign.html?3760manually then, that will work.

E2E tests

We use Webdriver.iowith Mochafor e2e tests.

Results at CI

If the e2e tests are failing you can check their output for 'failing' substring to see which specs are failing. Also build artifacts can give a hint on it - the failing tests will usually have screenshot for 6 retries like here. Note that EgisUI runs its main dependencies' (Portal, eSign, etc) e2e specs at CI, to make sure the EgisUI changes doesn't break them. This can be seen in e2e tests output like here.

Running locally

The best way to run e2e tests locally is via Docker container for PT, see its installation steps here. This will make sure you have the same PT configuration as CI does. After installing and running docker container for PT start webdriver-manager:

npm install -g webdriver-manager # needed once
# in a separate terminal window/tab
webdriver-manager update # this is needed at first installation and later after browsers update their versions
webdriver-manager start

Then load project's e2e fixtures and update the container apps:

cd MY_EGIS_DIR/eSign # or EgisUI, etc
export PT_API="" # put your docker's host and port here
cd e2e && ./fixtures.sh && cd ..
docker cp eSign.war my-pt:/opt/Papertrail/webapps # correct war filename for different project
docker cp ../EgisUI/EgisUI.war my-pt:/opt/Papertrail/webapps # if you want to test the project with your latest EgisUI build

Run the tests:

# Put your docker's host and port here, spec file(s) mask and the spec name(s) substring.
yarn test:e2e --baseUrl="" --specFiles="./wdio/**/Guide*Spec.js" --mochaOpts.grep="too early" --maxBrowserInstances=1 --mochaOpts.retries=1 


You can see locally which version is going to be published when your PR is merged with these steps:

# push egis/master to you-fork/master:
git checkout master
git fetch egis
git reset --hard egis/master
git push orgin +master

# switch back to your PR branch. Put your actual branch name here.
git checkout my-branch

# if not yet, create Github access token having push access to master, see https://github.com/semantic-release/github/blob/master/README.md#github-authentication
export GH_TOKEN=...

# Replace `repository.url` key in package.json to point to your fork temporarily: "git@github.com:my-gitusername/build-tools.git"

# Run semantic-release to find out the version number: 
BRANCH=my-branch yarn simple-semantic-release-pre

# Revert the `repository.url` change:
git checkout -- package.json

This applies both to build-tools and to any semantic-release enabled project of EgisUI family (EgisUI, Portal, eSign, etc).






扫码加入 JavaScript 社区



欢迎加入 JavaScript 社区