Skip to content

Latest commit

 

History

History
160 lines (125 loc) · 5.33 KB

static-assets.rst

File metadata and controls

160 lines (125 loc) · 5.33 KB
Raw

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
COMPREHENSIVE_THEME_DIRS (empty) Directories that will be searched when compiling themes. Separate multiple paths with colons (:). COMPREHENSIVE_THEME_DIRS COMPREHENSIVE_THEME_DIRS
WEBPACK_CONFIG_PATH webpack.prod.config.js Path to Webpack config file N/A N/A
STATIC_ROOT_LMS test_root/staticfiles Path to which LMS's static assets will be collected STATIC_ROOT N/A
STATIC_ROOT_CMS $STATIC_ROOT_LMS/studio. Path to which CMS's static assets will be collected N/A STATIC_ROOT
JS_ENV_EXTRA_CONFIG {}

Global configuration object available to edx-platform JS modules. Specified as a JSON string. Known keys:

  • TINYMCE_ADDITIONAL_PLUGINS
  • TINYMCE_CONFIG_OVERRIDES
 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
npm run build Combines npm run webpack and npm run compile-sass None
npm run build-dev Combines npm run webpack-dev and npm run compile-sass-dev None
npm run webpack Build JS bundles with Webpack Options are passed through to the webpack CLI
npm run webpack-dev Build JS bundles with Webpack for a development environment Options are passed through to the webpack CLI
npm run compile-sass Compile default and/or themed Sass Use --help to see available options
npm run compile-sass-dev Compile default and/or themed Sass, uncompressed with source comments Use --help to see available options
npm run watch Dev-only. Combine npm run watch-webpack and npm run watch-sass None.
npm run watch-webpack Dev-only. Wait for JS changes and re-run Webpack Options are passed through to the webpack CLI
npm run watch-sass 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.