=======================
Front End Build Process
=======================

This page documents additional information that may be useful when developing new features for Zulip that require front-end changes. For a more general overview, see the new feature tutorial. The code style documentation also has relevant information about how Zulip's code is structured.

Primary build process
=====================

Most of the existing JS in Zulip is written in IIFE-wrapped modules,
one per file in the `static/js` directory. When running Zulip in
development mode, each file is loaded seperately.  In production mode
(and when creating a release tarball using
`tools/build-release-tarball`), JavaScript files are concatenated and
minified.

If you add a new JavaScript file, it needs to be specified in the
`JS_SPECS` dictionary defined in `zproject/settings.py` to be included
in the concatenated file.

Webpack/CommonJS modules
========================

New JS written for Zulip can be written as CommonJS modules (bundled
using `webpack <https://webpack.github.io/>`_, though this will taken
care of automatically whenever ``run-dev.py`` is running). (CommonJS
is the same module format that Node uses, so see `the Node
documentation <https://nodejs.org/docs/latest/api/modules.html>` for
more information on the syntax.)

Benefits of using CommonJS modules over the `IIFE
<http://benalman.com/news/2010/11/immediately-invoked-function-expression/>`_
module approach:

* namespacing/module boilerplate will be added automatically in the bundling process
* dependencies between modules are more explicit and easier to trace
* no separate list of JS files needs to be maintained for concatenation and minification
* third-party libraries can be more easily installed/versioned using npm
* running the same code in the browser and in Node for testing is
  simplified (as both environments use the same module syntax)

The entry point file for the bundle generated by webpack is
``static/js/src/main.js``. Any modules you add will need to be
required from this file (or one of its dependencies) in order to be
included in the script bundle.

Adding static files
===================

To add a static file to the app (JavaScript, CSS, images, etc), first
add it to the appropriate place under ``static/``.

* Third-party files should all go in ``static/third/``.  Tag the commit
  with "[third]" when adding or modifying a third-party package.

* Our own JS lives under ``static/js``; CSS lives under ``static/styles``.

* JavaScript and CSS files are combined and minified in production. In
  this case all you need to do is add the filename to PIPELINE_CSS or
  JS_SPECS in ``zproject/settings.py``. (If you plan to only use the
  JS/CSS within the app proper, and not on the login page or other
  standalone pages, put it in the 'app' category.)

If you want to test minified files in development, look for the
``PIPELINE =`` line in ``zproject/settings.py`` and set it to ``True`` -- or
just set ``DEBUG = False``.

Note that ``static/html/{400,5xx}.html`` will only render properly if
minification is enabled, since they hardcode the path
``static/min/portico.css``.