build: npm run build (experimental)

[kdmccormick]

This PR implements much of: https://github.com/openedx/edx-platform/blob/master/docs/decisions/0017-reimplement-asset-processing.rst

This is backwards-compatible. paver update_assets should not be affected.

The new command warns that it is "experimental" for a few reasons:

1. Currently, npm run build will fail in the webpack phase unless you first run xmodule_assets. This will be changed soon, so I did not feel that it would be worthwhile to add a separate special npm run xmodule-assets step.
2. I have tested the new build, but not quite so thoroughly that I'd recommend it as the production default yet. In fact, once the xmodule_assets work lands, I'd like to share this on the forums so early adopters can try it out. That'll make me more comfortable making it the default over Paver.
3. The commands lack some top-level documentation. Once they stabilize more, I'd like to add a section to the README that explains how and when to use npm run build, its subcommands (npm run webpack[-dev], npm run compile-sass[-dev]), and the environemnt variables (STATIC_ROOT_LMS, etc).
4. npm run watch is not yet implemented. The current asset-watching that edx-platform and Tutor provide both rely on Paver.

Part of: #31604

Testing

There are a few different ways you could test this:

• Directly from your host, preview the Sass help & output:

  npm run compile-sass -- --help
  npm run compile-sass -- --dry --theme-dir=themes`

• Using Tutor Nightly dev:

  tutor mounts add path/to/edx-platform
  tutor dev run lms npm clean-install
  tutor dev run lms openedx-assets xmodule
  tutor dev run lms npm run build-dev
  tutor dev start -d

• Using Tutor Nightly prod:

  tutor mounts add path/to/edx-platform
  tutor local run lms npm clean-install
  tutor local run lms openedx-assets xmodule
  tutor local run lms npm run build
  tutor local start -d
  tutor local exec lms ./manage.py lms collectstatic --noinput
  tutor local exec cms ./manage.py cms collectstatic --noinput

• If you're adventurous: directly from your host, try:

  npm clean-install
  pip install -r requirements/edx/base.txt  # (would be assets.txt if not for xmodule_assets command)
  xmodule_assets common/static/xmodule
  npm run build-dev

[kdmccormick]

Notes for reviewers 👀

[kdmccormick]

I'd love to add comments here, but I can't since it's JSON. I do plan to document these in edx-platform's README, though, once they stabilize more.

In short:

• npm run webpack is a super thin wrapper around webpack.
• npm run compile-sass calls a script (currently written in Python, maybe one day written in Bash) which compiles Sass into CSS.
• npm run build is a combination of the above.
• The -dev targets are just simple variations of the base commands, for the convenience of developres.
• Wherever it was possible, I've written these so that:
  • You can override them with en vars, eg WEBPACK_CONFIG_PATH=my-special-config.js npm run webpack
  • You can provide extra options: npm run compile-sass -- --theme-dir=/my/cool/themes

[kdmccormick]

Constraint is moved over to constraints.txt so that it can be shared by assets.txt.

[kdmccormick]

This is a new env var, and is mentioned in the ADR. Eventually, I will document it in the edx-platform README.

[kdmccormick]

The goal of all the changes in this file is to provide some reasonable defaults for all env vars, so that webpack can be run on its own without having to supply a pile of environment variables.

We could have shoved all these defaults into the npm run webpack call in package.json, but that seemed worse than putting them here.

[feanil]

I tried to run this after running make clean in edx-platform.

npm install --legacy-peer-deps
npm run build

I got the following error:

Error: Cannot find module './common/static/xmodule/webpack.xmodule.config.js'

Did a file not get checked in or did I miss a step somewhere?

[kdmccormick]

@feanil Yep, you missed the xmodule_assets common/static/xmodule, which will be necessary until we merge #32685.

[feanil]

Ah, doh, missed the bottom of the description. But yes that was it, it works now, I was able to get all the assets built locally without any issue.

[edx-pipeline-bot]

2U Release Notice: This PR has been deployed to the edX staging environment in preparation for a release to production.

[edx-pipeline-bot]

2U Release Notice: This PR has been deployed to the edX production environment.

[edx-pipeline-bot]

2U Release Notice: This PR has been deployed to the edX production environment.