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 separately. 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, though this will be taken care of automatically whenever run-dev.py is running). (CommonJS is the same module format that Node uses, so see the Node documentation for more information on the syntax.)

Benefits of using CommonJS modules over the IIFE 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['STYLESHEET'] 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_ENABLED = 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.