mirror of https://github.com/zulip/zulip.git
71 lines
3.0 KiB
Markdown
71 lines
3.0 KiB
Markdown
# 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](https://webpack.github.io/), 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](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['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`.
|