Skip to content

Latest commit

 

History

History
executable file
·
116 lines (77 loc) · 7.86 KB

README.md

File metadata and controls

executable file
·
116 lines (77 loc) · 7.86 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

  • From inside the static_src directory, run npm install.
  • This will create:
    • a set of files inside node_modules which should be excluded from the repo
    • a package-lock.json file, which will record the exact version of node pacakages used.
  • Ensure you commit the package-lock.json file to your repo.
  • It may be advisable to upgrade the packages to their latest versions (see Using npm below)

Note that for easier maintenance the package-lock.json file is not committed to the wagtail-kit repo, but it should be committed in any new project created from wagtail-kit to ensure consistency between the packages used when different developers are working on the same project.

What's included

  • SASS CSS with auto-prefixing.
  • Browsersync for autoreloading.
  • Webpack and Babel for ES2015 support with module loading.
  • 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
  • Sass linting with sass-lint
  • JS linting with eslint
  • React support

Developing with it

  • To start the development environment, run npm start - to stop this process press ctrl + c.
  • This will start Browsersync and make the project available at http://localhost:3000/html/. 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.

Note that the build, debug and start commands will all rebuild node-sass before running the watch commands. This is because of differences between the way node-sass is installed when running vagrant up and when running npm install on the host machine.

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.

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.

Using and updating the tooling in wagtail-kit

You can remove this section from the readme file for new builds.

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

The easiest way to install new packages is to run npm install --save-dev package_name in wagtail-kit/built_image/ck_repo_name/ck_repo_name/static_src, but then copy the resultant changes to package.json over to /wagtail-kit/norwegian_ehealth/norwegian_ehealth/static_src.

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

Further details of the packages included

React specific packages

Bootstrap

We include Bootstrap 4.0 via scss includes in the main.scss file with @import 'vendor/bootstrap/bootstrap'; If Bootstrap CSS updates are needed for Bootstrap, please update files in the vendor\bootstrap folder. We import Bootstrap javascript in base.html via CDN along with the requirements for jQuery and Popper.