90 basic webpack

[JBCSU]

READY FOR REVIEW

Have at it, folks.

Summary

• replace the grunt build system with webpack

Needed By (Date)

• 3/27/2019 (5.0 release)

Urgency

• moderate - site builders' work will be easier when this is finished

Noteworthy changes

• npm has been upgraded to the latest version supported by nvm, 10.15.1. Make sure you have this version installed via nvm: nvm install 10.15.1 .
• Almost all npm packages have been removed. Many new ones have been added. All are now at their latest version.
• Generated css and js now lives in core/dist/css and core/dist/js, respectively. (They used to live in core/css and core/js.)
• Images referred to in .scss are now inlined in the generated.css as data.
• Images referred to in .twig files are (mostly) merely placeholders, and therefore, IMO, are not technically part of core. I have placed those images in a new root directory, img-placeholders. All images in that directory are copied to styleguide/img whenever you (re-)build the styleguide. Templates that refer to placeholders now refer to /img/... (absolute vs. relative url). (The one exception is the search icon in the search component. I propose the search icon be implemented via scss so it can be inlined / bundled with core.)

Known Issues

• CSS source maps aren't generating. No idea why. I'll keep trying.
• linters are not yet configured. That should be relatively quick, and I can probably get it in this PR.
• I have not (yet) provided an equivalent to browserSync. npm run watch will rebuild the .css and / or .js when corresponding source files change; however, you have to manually refresh your browser to load them. I believe I can implement this with webpack's hot module replacement, but that will take some time to configure properly. I would like to address that in separate PR.
• There is no watch on .twig or .json files, so you need to manually run npm run styleguide and refresh your browser when those files change. I don't think there's a way to implement this purely with npm (webpack is not involved in kss generation). Do we need to retain grunt for this?
• I have not (yet) provided an equivalent to grunt deploy. I haven't found an npm equivalent for grunt-deploy-site. Maybe we need to retain grunt for that one task???
• There are some codeclimate complaints. I believe most of these are issues we agreed to accept when we merged the nav branch, but we can discuss.

Steps to Test

⚠️
WARNING: This PR changes (almost) every build tool we use, including the version of node / npm. It also changes where output files are stored (from core to core/dist). It is challenging to switch between this branch and any other branch in the repo. You may want to clone this branch to a separate local repo on your machine to avoid the overhead of switching back and forth.
⚠️

One time only

• If you don't already have nvm's latest version of node / npm, do nvm install 10.15.1.

If you're testing in a pre-existing local repo:

1. rm -rf node_modules to wipe out all tools used in the grunt-based build env
2. npm cache clean --force to really wipe out everything
3. rm -rf styleguide to delete the assets generated by webpack (just for completeness)

Once you're In a clean repo (either a new one, or one you cleaned following the preceding steps):

1. nvm use to use the version of npm specified in .nvmrc, i.e. 10.15.1
2. npm install to install the webpack tools

To build decanter and the styleguide:

1. Build the assets and the styleguide
   1. npm run build to generate the dev version of css and js, and build the styleguide OR
   2. npm run dist to generate the prod version of css and js, and build the styleguide
2. You can also just build just the styleguide without rebuilding assets:
   1. npm run styleguide to generate the styleguide NB this does not build the css

If you decided to do this in the same local repo you use for other decanter development and you want to switch to a different branch

Before you switch to a different branch you should:

1. rm -rf node_modules to wipe out all tools used in this branch
2. npm cache clean --force to really wipe out everything
3. rm -rf styleguide to delete the assets generated by webpack (just for completeness)
4. check out the branch you want to switch to
5. nvm use to use the version of npm specified in .nvmrc, i.e. 9.10.1
6. npm install to re-install the grunt tools

Affected Projects or Products

• Final assets have moved from core/css/ and core/js/ to core/dist/css and core/dist/js. All products built on Decanter that load the pre-built assets will need to look in the new directories.

Associated Issues and/or People

• Issue Implement webpack #280

See Also

• PR Checklist

[JBCSU]

Oh. Looks like we used grunt to build the styleguide's custom css. Oy. 🙃

[JBCSU]

@sherakama I've committed all the changes we discussed today:

• reorganized the files into core/src and core/dist
• reorganized the webpack plugins, inspired by your 90-fixup, which resolved the problem with the clean plugin
• got devMode working (triggered off the name of the npm script: 'dist' = production, anything else is dev)
• replaced the clean plugin with the file manager plugin, and used it to
  • clean generated assets before building
  • copy generated assets to the styleguide after building (there's a comment explaining why I did it the way I did)
• merged master to get the search icon inlined as data

Thanks again for your help on this PR in general, and today in particular. I look forward to discussing tomorrow.