Wagtail builds with React in dev mode

README.md

Wagtail builds with React in dev mode

To create client-side extensions for Wagtail, it’s very useful to get full JavaScript error messages:

• React in development mode, with un-minified component traces, full error codes, and support for React DevTools
• JavaScript with source maps for more legible stack traces and debugger usage.

We can achieve this by building a release of Wagtail with Webpack’s mode set to development – which will in turn set process.env.NODE_ENV to development. This flag is what determines whether React is in development mode or not, and other debugging features within Wagtail and dependencies.

Step-by-step instructions

Based on Wagtail’s official release instructions, Package build

# 1. Download a copy of Wagtail.
git clone git@github.com:wagtail/wagtail.git
# 2. Move in and check out the version to build. Wagtail has tags for all released versions.
cd wagtail
git checkout v5.2.1
# 3. Switch to the correct Node version as defined in `.nvmrc` and install Node dependencies
nvm use
npm ci
# 4. Build the client-side code _in development mode_.
# This is the same command as `npm run build`, but with the `mode` set to `development` rather than production.
./node_modules/.bin/webpack --config ./client/webpack.config.js --mode development
# 5. Build a wheel.
pip install wheel
python setup.py bdist_wheel

Finally, install the wheel from its path in the desired project:

pip install ~/Dev/projects/wagtail/dist/wagtail-5.1.3.dev-py3-none-any.whl

Pre-built wheels for recent releases of Wagtail can be found in: Wagtail builds with React in dev mode

Alternatives

As it will become more and more common for Wagtail site implementers to build client-side extensions, we need a better alternative eventually.

One React build with feature flag to switch between modes

This seems appealing and possible but would only allow switching from React development mode to production – and the "production" build would still contain development-only aids, so wouldn’t be appropriate for real-world production usage.

Additionally, this wouldn’t cover source maps – only development aids within the code.

Source maps available with all Wagtail builds

This seems readily achieveable with our current release process as-is. The only drawback is the file size of source maps within the Wagtail releases.

Dual dev and production mode with all Wagtail builds

This would involve building client-side code for a release twice: once in dev mode, once in production mode. There could then be a project setting or similar API to switch between the two, similar to DEBUG for Django itself.