Skip to content

Latest commit

 

History

History
executable file
·
136 lines (96 loc) · 8.54 KB

front-end-tooling.md

File metadata and controls

executable file
·
136 lines (96 loc) · 8.54 KB
Raw

Front End Tooling

This set of tooling should form the basis for any new wagtail projects. It can also be used for custom django builds - simply copy the static_src directory from here to your build.

What's required

You can run the tooling within the VM where Node.js is pre-installed, but if you are using Mac OS, you will likely have issues with performance of npm install and other npm commands. It is adviced to Mac OS users to have node on the host machine. To install node on the host machine we recommend using nvm. Once you have nvm installed simply run nvm install to install and activate the version of node required for the project. Refer to the nvm documentation for more details about available commands.

Setting up a new project from the wagtail-kit tooling

The wagtail-kit tooling is versioned via package.json, and the package-lock.json lockfile pins all of the project’s direct and transitive dependencies. If you wish to start the project with up to date dependencies without doing manual upgrades, you can discard the lockfile and re-create it:

rm -rf node_modules
rm package-lock.json
npm install

Remember to then commit the updated package-lock.json.

What's included

  • Sass CSS with auto-prefixing.
  • Babel for ES2015+ support.
  • Browsersync for autoreloading.
  • Webpack for module bundling.
    • With babel-loader to process JavaScript.
    • With css-loader, postcss-loader, and sass-loader to process stylesheets.
  • Consideration for images, currently copying the directory only - to avoid slowdowns and non-essential dependancies. We encourage using SVG for UI vectors and pre-optimised UI photograph assets.
  • Build commands for generating testable or deployable assets only
  • CSS linting with stylelint
  • JS linting with eslint
  • Jest for JavaScript unit tests.
  • React support

Using and updating the tooling when making changes wagtail-kit

Updating and running the tooling in wagtail-kit is a bit fiddly, as if you create a node_modules folder in /wagtail-kit/bc the watcher script will throw an error.

Running the tooling whilst making changes

To run the tooling inside the wagtail-kit build, ensure that you run npm install from inside the built image, i.e. wagtail-kit/built_image/ck_repo_name

Making changes to the tooling

The easiest way to install new packages is to run npm install --save-dev package_name in wagtail-kit/built_image/ck_repo_name, but then copy the resultant changes to package.json and package-lock.json over to /wagtail-kit/bc in order to save and commit them. Note that when you do this you need to edit the copied files and change all instances of ck_repo_name to bc. Also make sure you turn off the watcher.py script before making changes in built_image.

Changes to the config files can be made directly in /wagtail-kit/bc.

Developing with it

  • To start the development environment, run npm start (or if that does not work npm run serve) - to stop this process press ctrl + c.
  • This will start Browsersync and make the project available at http://localhost:3000/. If another process is using this port, check terminal for an updated URL. You can change this configuation by modifying the browsersync.config.js file, documented here https://www.browsersync.io/docs/options.
  • Source files for developing your project are in static_src and the distribution folder for the compiled assets is static_compiled. Don't make direct changes to the static_compiled directory as they will be overwritten.

Using npm

  • Install all packages from package.json: npm install
  • Add new packages that are only required for development, e.g. tooling: npm install --save-dev package_name (this will add it to package.json and package-lock.json too)
  • Add new packages required in production, e.g. react: npm install --save-prod package_name
  • To upgrade packages run npm update package_name or npm update to update them all.

Tests

JavaScript unit tests for this project use Jest. Here are commands you can use:

# Run the whole test suite once.
npm run test
# Run the whole test suite, collecting test coverage information.
npm run test:coverage
# Start Jest in watch mode, to run tests on a subset of the files.
npm run test:watch

Deploying it

Build scripts

To only build assets for either development or production you can use

  • npm run build To build development assets
  • npm run build:prod To build assets with minification and vendor prefixes

Debug script

To test production, minified and vendor prefixed assets you can use

  • npm run debug To develop with a simple http server, no browsersync and production assets

React support

The wagtail-kit tooling now supports react out of the box.

Note that react is installed as a dependency and imported via main.js.

You can test that compilation of react is working by uncommenting the relevant lines in javascript/main.js and javascript/components/test-react.js. If you don't need react in your project, make sure you don't uncomment these lines or remove them completely. This will help to keep the compiled js file size down.

Third party libraries

We no longer have a 'vendor' folder for these. Instead find ones that are packaged as npm libraries and install them as dependencies (see 'using npm' above). If they have CSS that needs including, this can be imported directly from the node_modules folder - see the example for glide in main.scss.

Further details of the packages included

React specific packages