zulip/docs/front-end-build-process.md

# Static asset pipeline

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`.