Preparing static assets for edx-platform#
To run a production or development edx-platform site, you will need to build
assets assets using npm run ... commands. Furthermore, for a production
site, you will also need to collect assets.
Please note that developing new frontend pages for edx-platform is highly discouraged. New frontend pages should be built as micro-frontends (MFEs), which communicate with edx-platform over AJAX, but are built and deployed independently. Eventually, we expect that MFEs will replace all edx-platform frontend pages, except perhaps XBlock views.
Configuraiton#
To customize the static assets build, set some or all of these variable in your
shell environment before building or collecting static assets. As noted below,
some of these values will automatically become available as Django settings in
LMS or CMS (unless you separately override them in a private Django settings
file or LMS_CFG/CMS_CFG yaml file).
Environment Variable |
Default |
Description |
LMS Django Setting |
CMS Django Setting |
|---|---|---|---|---|
|
(empty) |
Directories that will be searched when compiling themes.
Separate multiple paths with colons ( |
|
|
|
|
Path to Webpack config file |
N/A |
N/A |
|
|
Path to which LMS’s static assets will be collected |
|
N/A |
|
|
Path to which CMS’s static assets will be collected |
N/A |
|
|
|
Global configuration object available to edx-platform JS modules. Specified as a JSON string. Known keys:
|
N/A |
N/A |
Build assets#
Building frontend assets requires an active Node and Python environment with dependencies installed:
npm clean-install
pip install -r requirements/edx/assets.txt
Once your environment variables are set and build dependencies are installed,
the one-sized-fits-all command to build assets is npm run build. If
your needs are more advanced, though, you can use some combination of the
commands below:
Command |
Meaning |
Options |
|---|---|---|
|
Combines |
None |
|
Combines |
None |
|
Build JS bundles with Webpack |
Options are passed through to the webpack CLI |
|
Build JS bundles with Webpack for a development environment |
Options are passed through to the webpack CLI |
|
Compile default and/or themed Sass |
Use |
|
Compile default and/or themed Sass, uncompressed with source comments |
Use |
|
Dev-only. Combine |
None. |
|
Dev-only. Wait for JS changes and re-run Webpack |
Options are passed through to the webpack CLI |
|
Dev-only. Wait for Sass changes and re-compile |
None. |
When supplying options to these commands, separate the command from the options
with a double-hyphen (--), like this:
npm run compile-sass -- --themes-dir /my/custom/themes/dir
Omitting the double-hyphen will pass the option to npm run itself, which
probably isn’t what you want to do.
If you would like to understand these more deeply, they are defined in
package.json. Please note: the npm run command interfaces are stable and
supported, but their underlying implementations may change without notice.
Collect assets#
Once assets are built, they can be collected into another directory for efficient serving. This is only necessary on production sites; developers can skip this section.
First, ensure you have a Python enironment with all edx-platform dependencies installed:
pip install -r requirements/edx/base.txt -e .
Next, download localized versions of edx-platform assets. Under the hood, this command uses the Open edX Atlas tool, which manages aggregated translations from edx-platform and its various plugins:
make pull_translations
Finally, invoke Django’s collectstatic command, once for the Learning Management System, and once for the Content Management Studio:
./manage.py lms collectstatic --noinput
./manage.py cms collectstatic --noinput
The --noinput option lets you avoid having to type “yes” when overwriting
existing collected assets.