mirror of
https://github.com/zulip/zulip.git
synced 2025-11-04 05:53:43 +00:00
72 lines
3.1 KiB
ReStructuredText
72 lines
3.1 KiB
ReStructuredText
=======================
|
|
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``.
|
|
|