frontend-changes-proposal.markdown

This is a proposal to simplify our frontend setup.

Motivation

The current frontend setup has some cognitive overhead in how we use it.

Problems:

1. Using third-party components is not straight forward.

• Have to remember what bower installs to public/client/bower_components/
• What is the relation of client/ and public/client/?
• How do we require a bower component?

2. Working with JS templates is not straight forward.

• Where do I write my application templates?
• How do I require templates for my app? (Backbone and Angular)

Current setup

client/
  common/
  desktop/
    app/
      inbound_stock_transfer_order/
        templates/                        # Contains Angular partials
        app.js
        require.config.js
        ...
      ...
    ...
  mobile/
  ...
public/
  client/
    app/                  # Copied from client/ folder via gulp
      common/
      desktop/
        app/
          inbound_stock_transfer_order/
      mobile/
      isto-templates.js   # Compiled from client/desktop/app/inbound_stock_transfer_order/templates/
      ...
    bower_components/     # Third-party components
      angular/
      ...
  client-built/           # Compiled from public/client

Notes:

• To use third-party components, you must require from ../bower_components because it is one directory up from RequireJS baseUrl. This is weird, and is partly why we reconfigure paths using require.config().
• client/ gets copied to public/client/app/, which makes paths harder to understand. (e.g. public/client/app/desktop/app)
• To require a template, you must use the name configured within client/modules.json. e.g. for ISTO it is require(['isto-templates']).

Proposed setup

client/
    bower_components/       # bower_components is now within client folder
    common/
    desktop/
      app/
        inbound_stock_transfer_order/
          templates/
          app.js
          require.config.js
          ...
    mobile/
    ...
public/
  client/                               # Moved from public/client/app to public/client
    desktop/
      app/
        inbound_stock_transfer_order/   # Same as before but includes templates.js so path matches source
          app.js
          require.config.js
          templates.js
          ...
  client-built/

Notes:

• All JS modules are now served from baseUrl (public/client), and we no longer need to go one directory up.
  • Paths are easier to reason about, because client/ contains all modules needed.
• We will need to copy bower_components/**/*.js from client/ to public/client.
• Template path now matches source. e.g. require(['desktop/app/inbound_stock_transfer_order/templates']).

Current benchmarks:

• gulp watch takes 15 seconds to startup.
• gulp watch uses up 100 MB of memory on startup.
• gulp watch uses up 200 MB of memory once warmed up (after ~10-15 JS changes).

New setup benchmarks (new folder structure, copying bower_components):

• gulp watch takes 13 seconds to startup.
• gulp watch takes up 200 MB of memory on startup.
• gulp watch takes up 200 MB of memory once warmed up (after ~10-15 JS changes).