update docs to match our new frontend stack (#4860)

https://github.com/mozilla/sumo-project/issues/885

.vscode/README.md

@@ -14,7 +14,7 @@ In the vscode command palette (Ctrl+Shift+P) build and launch the container:
 
 Once vscode has reopened in the container, open a terminal (View > Terminal) and start browser-sync and the on-demand asset rebuilding:
 ```
-npm run start-in-container
+npm start
 ```
 
 And run kitsune through the debugger:
@@ -26,7 +26,7 @@ And run kitsune through the debugger:
 
 To run kitsune without debugging, ensure you start browser-sync and asset rebuilding as before with:
 ```
-npm run start-in-container
+npm start
 ```
 
 And run kitsune with this vscode command instead:

docs/frontend.md

@@ -0,0 +1,126 @@
+# Frontend Infrastructure
+
+We use [Webpack](https://webpack.js.org/) to manage our frontend assets.
+Its configuration lives in `webpack.config.js`,
+which imports files from  the `webpack/` folder.
+
+To build the development Webpack bundle run `npm run webpack:build`.
+To watch files
+(excluding the Webpack configuration files)
+and automatically rebuild the development Webpack bundle when they change,
+run `npm run webpack:watch`.
+
+To build a production Webpack bundle run `npm run webpack:build:prod`.
+
+Webpack puts its build output in the `dist/` folder,
+which is picked up by Django staticfiles.
+
+## Entry points
+
+`webpack/entrypoints.js` defines each of our entry points,
+and the files that should be bundled into them.
+
+For now this is very verbose,
+as it mirrors the configuration we used in our old Django Pipeline setup.
+However over time we'll leverage the ability to import libraries directly in the JS files which require them,
+reducing the number of files we need to list here.
+
+When building a development bundle,
+we generate sourcemaps to make in-browser debugging easier.
+
+When building a production bundle,
+we add a hash to the output file names,
+to allow for cache-busting on staging and production.
+
+### Loading in Django
+
+We use the [HtmlWebpackPlugin](https://webpack.js.org/plugins/html-webpack-plugin/) to generate HTML files for each of our entry points,
+which includes the script tags
+(and link tags, explained in the CSS section below)
+needed to load the hashed chunks that form each entry point.
+This configuration lives in `webpack/entrypoints-html.js`.
+
+In Django,
+templates can set the `scripts` variable to specify which entry points should be loaded for that template.
+
+### Loading CSS
+
+There is a special entry point `screen` which contains all our CSS,
+and is treated slightly differently by `webpack/entrypoints-html.js`.
+Since Webpack is primarily a JS bundler it emits an empty JS file,
+which we have no need to include in our site,
+so `webpack/entrypoints-html.js` ignores it.
+
+## Javascript
+
+All our JS files are run through [Babel](https://babeljs.io/),
+allowing us to use modern JS syntax now,
+without having to worry whether our users' browsers support it.
+
+Webpack automatically minifies our JS when building the production bundle.
+
+### Globals
+
+Because most of our JS stack was written well before modules were a thing,
+many files place variables in the global scope for other files to use.
+However in Webpack,
+unless a file explicitly places a variable under `window`,
+we have to expose each of those variables manually.
+
+This is done in `webpack/global-expose-rules.js`.
+Like above,
+over time we'll leverage imports to reduce the number of variables we have to expose to the global scope.
+
+## Stylesheets
+
+Our stylesheets are written in [Sass](https://sass-lang.com/),
+using its SCSS syntax (`.scss`).
+
+We use the [MiniCssExtractPlugin](https://webpack.js.org/plugins/mini-css-extract-plugin/) to separate our CSS from our JS files.
+
+### PostCSS
+
+We use the [postcss-loader](https://webpack.js.org/loaders/postcss-loader/) to process our css files with postcss.
+Its configuration lives in `postcss.config.js`.
+
+When building a production bundle,
+[cssnano](https://cssnano.co/) minifies our CSS.
+
+## Images
+
+Images directly imported in JS files,
+or referenced in CSS files,
+are copied by Webpack into the build directory,
+after renaming and optimizing them.
+
+### In Django
+
+Aside from managing images directly imported in JS and CSS files,
+we also make use of Webpack to manage images used in Django itself,
+in Jinja2 templates and Python code.
+
+To do this,
+we make use of the [CopyWebpackPlugin](https://webpack.js.org/plugins/copy-webpack-plugin/) to copy images under certain paths into the build directory,
+after processing them through the asset pipeline.
+
+We then hook into the Webpack build process,
+in `webpack/asset-json-plugin.js`,
+to generate an original to build path mapping in the `dist/source-to-asset.json` file.
+We shorten the original path as explained below.
+
+Included images are those:
+
+* under the Protocol icons directory: `node_modules/@mozilla-protocol/core/protocol/img/icons/`,
+shortened to `protocol/img/icons/`
+* under the static image directory for any Django app: `kitsune/*/static/**/img/`,
+shortened to `**/img/`
+
+In Django,
+the `webpack_static` helper loads the mapping,
+and is used to get an output path for any image needed from those directories.
+
+### Optimization
+
+In the Webpack pipeline,
+PNGs are run through optipng,
+and SVGs are run through svgo.

docs/frontend.rst

@@ -1,56 +0,0 @@
-=======================
-Frontend Infrastructure
-=======================
-
-.. warning::
-    This section of documentation may be outdated.
-
-Frontends assets for Kitsune are managed through `Django Pipeline`_.
-
-.. _Django Pipeline: https://django-pipeline.readthedocs.io/
-
-
-Bundles
-=======
-
-To reduce the number of requests per page and increase overall performance,
-JS and CSS resources are grouped into *bundles*. These are defined in
-``kitsune/bundles.py``, and are loaded into pages with template tags. Each
-bundle provides a list of files which will be compiled (if necessary), minified,
-and concatenated into the final bundle product.
-
-In development, the minification and concatenation steps are skipped. In
-production, each file is renamed to contain a hash of it's contents in the
-name, and files are rewritten to account for the changed names. This is
-called cache busting, and allows the CDN to be more aggressive in caching these
-resources, and for clients to get updates faster when we make changes.
-
-Style Sheets
-============
-
-The styles written for Kitsune is mostly written in `Sass`_ using the SCSS synatax.
-
-Sass files are recognized by an extension of ``.scss``.
-
-.. _Sass: https://sass-lang.com/
-
-Javascript
-==========
-
-There are a few kinds of Javascript in use in Kitsune.
-
-Plain JS
---------
-
-Plain JS is not suspect to any compilation step, and is only minified and
-concatenated. Plain JS files should be written to conform to ES5 standards, for
-compatibility.
-
-Plain JS files have an extension of ``.js``.
-
-ES6 and beyond
---------------
-
-Files with an extension of ``.es6`` are compiled by `Babel`_ to ES5.
-
-.. _Babel: https://babeljs.io/

docs/hacking_howto.md

@@ -18,7 +18,7 @@ and follow the following steps.
     git clone https://github.com/mozilla/kitsune.git
     ```
 
-2. Pull base Kitsune Docker images, run `collectstatic`, create your database, and install node packages.
+2. Pull base Kitsune Docker images, install node packages and build the Webpack bundle, and create your database.
     ```
     make init
     make build
@@ -59,8 +59,7 @@ instead of `make shell` as the latter does not bind port 8000 which you need to
 
 Run `make help` to see other helpful commands.
 
-Finally you can run the development server with instance reloading through
+Then you can run the Webpack build with instant reloading through browser-sync:
-browser-sync.
 
 ```
 npm start

package.json

@@ -28,10 +28,9 @@
     "watch:docstyles": "onchange 'assets/sumo/css/screen.css' -- npm run build:docs:copystyles",
     "watch:docjs": "onchange 'kitsune/sumo/static/sumo/js/**/*.js' -- npm run build:docs:copyjs",
     "watch": "npm run build && concurrently --raw npm:watch:*",
-    "browser-sync": "browser-sync start --no-open --files \"kitsune/**/*.html\" \"assets/sumo/css/screen.css\" \"kitsune/**/.py\" \"kitsune/**/.js\" \"kitsune/**/.json\" --proxy 127.0.0.1:8000 --reload-delay=300",
+    "browser-sync": "browser-sync start --no-open --files \"kitsune/**/*.html\" \"dist\" --proxy 127.0.0.1:8000",
     "browser-sync:docs": "browser-sync start --no-open --serveStatic \"styleguide/build\" --files \"styleguide/build/**/*\" --port 4000 --reload-delay=300",
-    "start": "concurrently --raw --kill-others \"make run\" \"npm run watch\" \"npm run browser-sync\"",
+    "start": "concurrently --raw --kill-others \"npm run webpack:watch\" \"npm run browser-sync\"",
-    "start-in-container": "concurrently --raw --kill-others \"npm run watch\" \"npm run browser-sync\"",
     "lint:webpack": "npx eslint --no-eslintrc -c webpack/eslintrc.js --ignore-pattern '**/tests/**' kitsune",
     "webpack:build": "npx webpack build --mode development",
     "webpack:build:prod": "npx webpack build --mode production",